{
  "canonical_name": "s4b7-ai/s4b7-ai-skills",
  "compilation_id": "pack_34875ea66c524659ba5c7daa39985912",
  "created_at": "2026-05-19T06:23:28.480711+00:00",
  "created_by": "project-pack-compiler",
  "feedback": {
    "carrier_selection_notes": [
      "viable_asset_types=skill, recipe, host_instruction, eval, preflight",
      "recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
    ],
    "evidence_delta": {
      "confirmed_claims": [
        "identity_anchor_present",
        "capability_and_host_targets_present",
        "install_path_declared_or_better"
      ],
      "missing_required_fields": [],
      "must_verify_forwarded": [
        "Run or inspect `npx skills` in an isolated environment.",
        "Confirm the project exposes the claimed capability to at least one target host."
      ],
      "quickstart_execution_scope": "allowlisted_sandbox_smoke",
      "sandbox_command": "npx skills",
      "sandbox_container_image": "node:22-slim",
      "sandbox_execution_backend": "docker",
      "sandbox_planner_decision": "deterministic_isolated_install",
      "sandbox_validation_id": "sbx_a81d6098117f4bdf96be23d791a9501a"
    },
    "feedback_event_type": "project_pack_compilation_feedback",
    "learning_candidate_reasons": [],
    "template_gaps": []
  },
  "identity": {
    "canonical_id": "project_cdec0a5142d898e11238af23b1b38777",
    "canonical_name": "s4b7-ai/s4b7-ai-skills",
    "homepage_url": null,
    "license": "unknown",
    "repo_url": "https://github.com/s4b7-ai/s4b7-ai-skills",
    "slug": "s4b7-ai-skills",
    "source_packet_id": "phit_425c78561d8543b7a3183f94acf7de5e",
    "source_validation_id": "dval_b4079d7060694641894b0f348329da88"
  },
  "merchandising": {
    "best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
    "github_forks": 0,
    "github_stars": 0,
    "one_liner_en": "Agent skills for AI/ML workflows — model orchestration, multi-model inference, agent building, policy steering, and self-improvement loops.",
    "one_liner_zh": "Agent skills for AI/ML workflows — model orchestration, multi-model inference, agent building, policy steering, and self-improvement loops.",
    "primary_category": {
      "category_id": "software-development",
      "confidence": "medium",
      "name_en": "Software Development",
      "name_zh": "软件开发与交付",
      "reason": "matched_keywords:git, cli"
    },
    "target_user": "使用 local_cli 等宿主 AI 的用户",
    "title_en": "s4b7-ai-skills",
    "title_zh": "s4b7-ai-skills 能力包",
    "visible_tags": [
      {
        "label_en": "Browser Agents",
        "label_zh": "浏览器 Agent",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "product_domain-browser-agents",
        "type": "product_domain"
      },
      {
        "label_en": "Web Task Automation",
        "label_zh": "网页任务自动化",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "user_job-web-task-automation",
        "type": "user_job"
      },
      {
        "label_en": "Browser Automation",
        "label_zh": "浏览器自动化",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "core_capability-browser-automation",
        "type": "core_capability"
      },
      {
        "label_en": "Page Observation and Action Planning",
        "label_zh": "页面观察与动作规划",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "workflow_pattern-page-observation-and-action-planning",
        "type": "workflow_pattern"
      },
      {
        "label_en": "Evaluation Suite",
        "label_zh": "评测体系",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "selection_signal-evaluation-suite",
        "type": "selection_signal"
      }
    ]
  },
  "packet_id": "phit_425c78561d8543b7a3183f94acf7de5e",
  "page_model": {
    "artifacts": {
      "artifact_slug": "s4b7-ai-skills",
      "files": [
        "PROJECT_PACK.json",
        "QUICK_START.md",
        "PROMPT_PREVIEW.md",
        "HUMAN_MANUAL.md",
        "AI_CONTEXT_PACK.md",
        "BOUNDARY_RISK_CARD.md",
        "PITFALL_LOG.md",
        "REPO_INSPECTION.json",
        "REPO_INSPECTION.md",
        "CAPABILITY_CONTRACT.json",
        "EVIDENCE_INDEX.json",
        "CLAIM_GRAPH.json"
      ],
      "required_files": [
        "PROJECT_PACK.json",
        "QUICK_START.md",
        "PROMPT_PREVIEW.md",
        "HUMAN_MANUAL.md",
        "AI_CONTEXT_PACK.md",
        "BOUNDARY_RISK_CARD.md",
        "PITFALL_LOG.md",
        "REPO_INSPECTION.json"
      ]
    },
    "detail": {
      "capability_source": "Project Hit Packet + DownstreamValidationResult",
      "commands": [
        {
          "command": "npx skills",
          "label": "Node.js / npx · 官方安装入口",
          "source": "https://github.com/s4b7-ai/s4b7-ai-skills#readme",
          "verified": true
        }
      ],
      "display_tags": [
        "浏览器 Agent",
        "网页任务自动化",
        "浏览器自动化",
        "页面观察与动作规划",
        "评测体系"
      ],
      "eyebrow": "软件开发与交付",
      "glance": [
        {
          "body": "判断自己是不是目标用户。",
          "label": "最适合谁",
          "value": "需要软件开发与交付能力，并使用 local_cli的用户"
        },
        {
          "body": "先理解能力边界，再决定是否继续。",
          "label": "核心价值",
          "value": "Agent skills for AI/ML workflows — model orchestration, multi-model inference, agent building, policy steering, and self-improvement loops."
        },
        {
          "body": "未完成验证前保持审慎。",
          "label": "继续前",
          "value": "publish to Doramagic.ai project surfaces"
        }
      ],
      "guardrail_source": "Boundary & Risk Card",
      "guardrails": [
        {
          "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
          "label": "Check 1",
          "value": "不要把试用当真实运行"
        },
        {
          "body": "local_cli",
          "label": "Check 2",
          "value": "确认宿主兼容"
        },
        {
          "body": "publish to Doramagic.ai project surfaces",
          "label": "Check 3",
          "value": "先隔离验证"
        }
      ],
      "mode": "skill, recipe, host_instruction, eval, preflight",
      "pitfall_log": {
        "items": [
          {
            "body": "仓库名 `s4b7-ai-skills` 与安装入口 `skills` 不完全一致。",
            "category": "身份坑",
            "evidence": [
              "identity.distribution | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | repo=s4b7-ai-skills; install=skills"
            ],
            "severity": "medium",
            "suggested_check": "在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。",
            "title": "仓库名和安装名不一致",
            "user_impact": "用户照着仓库名搜索包或照着包名找仓库时容易走错入口。"
          },
          {
            "body": "README/documentation is current enough for a first validation pass.",
            "category": "能力坑",
            "evidence": [
              "capability.assumptions | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | README/documentation is current enough for a first validation pass."
            ],
            "severity": "medium",
            "suggested_check": "将假设转成下游验证清单。",
            "title": "能力判断依赖假设",
            "user_impact": "假设不成立时，用户拿不到承诺的能力。"
          },
          {
            "body": "未记录 last_activity_observed。",
            "category": "维护坑",
            "evidence": [
              "evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | last_activity_observed missing"
            ],
            "severity": "medium",
            "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
            "title": "维护活跃度未知",
            "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
          },
          {
            "body": "no_demo",
            "category": "安全/权限坑",
            "evidence": [
              "downstream_validation.risk_items | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | no_demo; severity=medium"
            ],
            "severity": "medium",
            "suggested_check": "进入安全/权限治理复核队列。",
            "title": "下游验证发现风险项",
            "user_impact": "下游已经要求复核，不能在页面中弱化。"
          },
          {
            "body": "no_demo",
            "category": "安全/权限坑",
            "evidence": [
              "risks.scoring_risks | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | no_demo; severity=medium"
            ],
            "severity": "medium",
            "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
            "title": "存在评分风险",
            "user_impact": "风险会影响是否适合普通用户安装。"
          },
          {
            "body": "issue_or_pr_quality=unknown。",
            "category": "维护坑",
            "evidence": [
              "evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | issue_or_pr_quality=unknown"
            ],
            "severity": "low",
            "suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
            "title": "issue/PR 响应质量未知",
            "user_impact": "用户无法判断遇到问题后是否有人维护。"
          },
          {
            "body": "release_recency=unknown。",
            "category": "维护坑",
            "evidence": [
              "evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | release_recency=unknown"
            ],
            "severity": "low",
            "suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
            "title": "发布节奏不明确",
            "user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
          }
        ],
        "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
        "summary": "发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。",
        "title": "踩坑日志"
      },
      "snapshot": {
        "contributors": 1,
        "forks": 0,
        "license": "unknown",
        "note": "站点快照，非实时质量证明；用于开工前背景判断。",
        "stars": 0
      },
      "source_url": "https://github.com/s4b7-ai/s4b7-ai-skills",
      "steps": [
        {
          "body": "不安装项目，先体验能力节奏。",
          "code": "preview",
          "title": "先试 Prompt"
        },
        {
          "body": "理解输入、输出、失败模式和边界。",
          "code": "manual",
          "title": "读说明书"
        },
        {
          "body": "把上下文交给宿主 AI 继续工作。",
          "code": "context",
          "title": "带给 AI"
        },
        {
          "body": "进入主力环境前先完成安装入口与风险边界验证。",
          "code": "verify",
          "title": "沙箱验证"
        }
      ],
      "subtitle": "Agent skills for AI/ML workflows — model orchestration, multi-model inference, agent building, policy steering, and self-improvement loops.",
      "title": "s4b7-ai-skills 能力包",
      "trial_prompt": "# s4b7-ai-skills - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for s4b7-ai/s4b7-ai-skills.\n\nProject:\n- Name: s4b7-ai-skills\n- Repository: https://github.com/s4b7-ai/s4b7-ai-skills\n- Summary: Agent skills for AI/ML workflows — model orchestration, multi-model inference, agent building, policy steering, and self-improvement loops.\n- Host target: local_cli\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Agent skills for AI/ML workflows — model orchestration, multi-model inference, agent building, policy steering, and self-improvement loops.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n- Capability 2: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. skill-structure: Skill Structure & Anatomy. Produce one small intermediate artifact and wait for confirmation.\n2. langgraph-agent: LangGraph Agent Development. Produce one small intermediate artifact and wait for confirmation.\n3. ai-sdk-core: AI SDK Core - Vercel Integration. Produce one small intermediate artifact and wait for confirmation.\n4. write-a-skill: Write A Skill - Authoring Guide. Produce one small intermediate artifact and wait for confirmation.\n5. crystallize: Crystallize - Pattern Extraction. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/s4b7-ai/s4b7-ai-skills\n- https://github.com/s4b7-ai/s4b7-ai-skills#readme\n- skills/a2a-orchestrator/SKILL.md\n- skills/aacp/SKILL.md\n- skills/acp-delegate-auto/SKILL.md\n- skills/agent-cryst/SKILL.md\n- skills/ai-sdk-core/SKILL.md\n- skills/codex-context/SKILL.md\n- skills/codex-latex/SKILL.md\n- skills/codex-policy-steering/SKILL.md\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
      "voices": [
        {
          "body": "当前没有项目级社区来源；不会把未抓取讨论包装成社会证明。",
          "items": [],
          "status": "待发现 Agent 补证",
          "title": "社区讨论"
        }
      ]
    },
    "homepage_card": {
      "category": "软件开发与交付",
      "desc": "Agent skills for AI/ML workflows — model orchestration, multi-model inference, agent building, policy steering, and self-improvement loops.",
      "effort": "安装已验证",
      "forks": 0,
      "icon": "code",
      "name": "s4b7-ai-skills 能力包",
      "risk": "需复核",
      "slug": "s4b7-ai-skills",
      "stars": 0,
      "tags": [
        "浏览器 Agent",
        "网页任务自动化",
        "浏览器自动化",
        "页面观察与动作规划",
        "评测体系"
      ],
      "thumb": "gray",
      "type": "Skill Pack"
    },
    "manual": {
      "markdown": "# https://github.com/s4b7-ai/s4b7-ai-skills 项目说明书\n\n生成时间：2026-05-16 00:22:44 UTC\n\n## 目录\n\n- [Home - Repository Overview](#home)\n- [Installation Guide](#installation)\n- [Skill Structure & Anatomy](#skill-structure)\n- [Skill Dependencies & Metadata](#skill-dependencies)\n- [LangGraph Agent Development](#langgraph-agent)\n- [AI SDK Core - Vercel Integration](#ai-sdk-core)\n- [Agent Crystallization Protocol](#agent-cryst)\n- [Write A Skill - Authoring Guide](#write-a-skill)\n- [Crystallize - Pattern Extraction](#crystallize)\n- [Skill Surgery R&D](#skill-surgery-rd)\n\n<a id='home'></a>\n\n## Home - Repository Overview\n\n### 相关页面\n\n相关主题：[Installation Guide](#installation), [Skill Structure & Anatomy](#skill-structure)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/qmd-memory/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/qmd-memory/SKILL.md)\n- [skills/codex-context/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-context/SKILL.md)\n- [skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)\n- [skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n- [skills/codex-latex/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-latex/SKILL.md)\n- [skills/patent-queue/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/patent-queue/SKILL.md)\n- [skills/shadow-engg/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-engg/SKILL.md)\n- [skills/ai-sdk-core/references/v5-breaking-changes.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/v5-breaking-changes.md)\n</details>\n\n# Home - Repository Overview\n\n## Introduction\n\nThe `s4b7-ai/s4b7-ai-skills` repository is a **skills library** designed to extend and automate AI agent capabilities across multiple domains. This repository serves as a central hub for specialized operational skills that enable AI systems (such as Codex, Claude, Gemini, and custom shadow agents) to perform complex tasks including memory management, code refactoring, patent processing, multi-model querying, and engineering intelligence.\n\nThe skills are structured as reusable, modular units that can be loaded by AI agents on demand based on contextual triggers. Each skill encapsulates domain-specific workflows, CLI commands, API integrations, and operational patterns.\n\n资料来源：[skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n\n---\n\n## Repository Architecture\n\n### Directory Structure\n\n```\ns4b7-ai-skills/\n├── skills/\n│   ├── qmd-memory/              # Memory extraction and management\n│   ├── codex-context/           # Codex configuration and context\n│   ├── shadow-refactor/         # Code refactoring automation\n│   ├── write-a-skill/           # Skill creation framework\n│   ├── codex-latex/             # LaTeX document generation\n│   ├── patent-queue/            # Patent portfolio management\n│   ├── multi-model-query/       # Multi-AI synthesis\n│   ├── shadow-continuity/        # Long-term context preservation\n│   ├── acp-delegate-auto/       # Task delegation routing\n│   ├── command-center/          # Engineering workflow automation\n│   ├── crystallize/             # Pattern extraction from sessions\n│   ├── shadow-mcp-gadgets/      # MCP server federation\n│   ├── shadow-patent-factory/   # Patent drafting automation\n│   ├── shadow-engg/             # Engineering intelligence\n│   ├── shadow-pi/               # CRUD operations framework\n│   └── ai-sdk-core/             # AI SDK references\n│       └── references/\n│           └── v5-breaking-changes.md\n```\n\n资料来源：[skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n\n### Skill Composition Pattern\n\nEach skill follows a standardized structure for consistency:\n\n| Component | Purpose | Location |\n|-----------|---------|----------|\n| `SKILL.md` | Primary definition with workflows, triggers, and commands | Root of skill directory |\n| `scripts/` | Deterministic utility scripts | Optional, under skill directory |\n| `references/` | Supporting documentation | Optional subdirectories |\n\n资料来源：[skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n\n---\n\n## Skill Categories\n\n### Memory & Context Management\n\n| Skill | Purpose | Triggers |\n|-------|---------|----------|\n| `qmd-memory` | Memory extraction, storage, and recall with deduplication tracking | `memory`, `extract`, `remember` |\n| `shadow-continuity` | Long-term context preservation across sessions | `continuity`, `context preservation` |\n| `shadow-mcp-gadgets` | MCP server federation for unified context assembly | `esp.assemble`, `/renew-ctx` |\n\n资料来源：[skills/qmd-memory/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/qmd-memory/SKILL.md), [skills/shadow-mcp-gadgets/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mcp-gadgets/SKILL.md)\n\n### Code Engineering\n\n| Skill | Purpose | Triggers |\n|-------|---------|----------|\n| `shadow-refactor` | Automated refactoring with TDD loop | `refactor`, `patterns`, `hotspot` |\n| `write-a-skill` | Framework for creating new skills | `write-a-skill`, `create skill` |\n| `shadow-pi` | Standard CRUD operations for data | `crud`, `data operations` |\n\n资料来源：[skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md), [skills/shadow-pi/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-pi/SKILL.md)\n\n### Document & Patent Processing\n\n| Skill | Purpose | Triggers |\n|-------|---------|----------|\n| `codex-latex` | LaTeX document compilation and formatting | `latex`, `pdf`, `document` |\n| `patent-queue` | Patent portfolio tracking and synthesis | `patent`, `portfolio` |\n| `shadow-patent-factory` | Automated patent drafting with SP-ID system | `factory.new`, `factory.draft` |\n\n资料来源：[skills/codex-latex/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-latex/SKILL.md), [skills/patent-queue/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/patent-queue/SKILL.md), [skills/shadow-patent-factory/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-patent-factory/SKILL.md)\n\n### Multi-Model AI Orchestration\n\n| Skill | Purpose | Triggers |\n|-------|---------|----------|\n| `acp-delegate-auto` | Intelligent task routing to AI providers | `delegate`, `route to` |\n| `multi-model-query` | Synthesis across multiple AI models | `query`, `synthesize`, `compare` |\n\n资料来源：[skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md), [skills/multi-model-query/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/multi-model-query/SKILL.md)\n\n### Engineering & Business Operations\n\n| Skill | Purpose | Triggers |\n|-------|---------|----------|\n| `shadow-engg` | Automotive competitive intelligence | `engineering`, `competitive intel` |\n| `command-center` | Engineering workflow automation | `scar`, `ppap`, `upscaler` |\n| `crystallize` | Pattern extraction from AI sessions | `crystallize`, `extract pattern` |\n\n资料来源：[skills/shadow-engg/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-engg/SKILL.md), [skills/command-center/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/command-center/SKILL.md), [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n---\n\n## Core Workflow Patterns\n\n### Universal Pipeline Architecture\n\nMost skills follow a consistent operational pipeline:\n\n```mermaid\ngraph TD\n    A[Intent] --> B[Resolve Target]\n    B --> C[Execute Operation]\n    C --> D[Verify Result]\n    D --> E[Report Findings]\n    \n    F[Artifact Routing] --> G[Report Storage]\n    G --> H[ShadowArchive/80-reports/]\n```\n\n资料来源：[skills/codex-latex/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-latex/SKILL.md)\n\n### Fallback Chain Pattern\n\nSkills implement a fallback chain to ensure resilience:\n\n```mermaid\ngraph LR\n    A[Primary Action] --> B{Failed?}\n    B -->|Yes| C[Fallback 1]\n    C --> D{Failed?}\n    D -->|Yes| E[Fallback 2]\n    E --> F{Failed?}\n    F -->|Yes| G[Last Resort]\n```\n\nCommon fallbacks include:\n1. Primary CLI/tool execution\n2. Static analysis or manual methods\n3. Alternative API or local model (e.g., Ollama)\n4. Inline summary generation\n\n资料来源：[skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md), [skills/patent-queue/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/patent-queue/SKILL.md)\n\n---\n\n## AI Provider Integration\n\n### Delegation Routing Heuristics\n\nThe `acp-delegate-auto` skill routes tasks based on keyword detection:\n\n| Prompt Contains | Route To |\n|----------------|----------|\n| `write`, `implement`, `refactor`, `debug code` | codex |\n| `research`, `summarize`, `find`, `compare` | gemini |\n| `translate`, `JP`, `Japanese` | Codex |\n| `local`, `private`, `no cloud` | ollama |\n| `review`, `architect`, `design` | Codex |\n| `quickly`, `fast`, `brief` | ollama |\n\n### Model Selection\n\n| Provider | Model | Use Case |\n|----------|-------|----------|\n| Codex (via MCP) | `Codex-sonnet-4-6` | Default complex tasks |\n| Codex (via ACP) | `Codex-opus-4-6` | High complexity |\n| Gemini (OpenRouter) | `google/gemini-2.0-flash-001` | Speed priority |\n| Gemini (OpenRouter) | `google/gemini-2.5-pro` | Depth priority |\n| Ollama (local) | `qwen3:8b` | Private, offline |\n\n资料来源：[skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n\n---\n\n## Memory System Architecture\n\n### Memory Kinds and Tags\n\nThe `qmd-memory` skill supports structured memory classification:\n\n```mermaid\ngraph TD\n    A[Memory Store] --> B[Kinds]\n    A --> C[Tags]\n    \n    B --> B1[fact]\n    B --> B2[commitment]\n    B --> B3[decision]\n    B --> B4[preference]\n    B --> B5[context]\n    \n    C --> C1[work]\n    C --> C2[privacy]\n    C --> C3[user-defined]\n```\n\n**CLI Commands:**\n```bash\nqmd-memory store \"content\" --kind fact --tag work\nqmd-memory recall --kind fact --limit 5\nqmd-memory extract notes.md --source-id \"file:notes.md\"\n```\n\n资料来源：[skills/qmd-memory/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/qmd-memory/SKILL.md)\n\n---\n\n## Patent Processing Pipeline\n\n### Patent Lifecycle Management\n\n```mermaid\ngraph LR\n    A[Idea] --> B[SP-ID Assignment]\n    B --> C[Specification Draft]\n    C --> D[Claims Draft]\n    D --> E[Prior Art Search]\n    E --> F[Filing Guide]\n    F --> G[Registry]\n    G --> H[Obsidian Export]\n    \n    A1[Auto-Patent CLI] --> B\n    H --> I[Portfolio README]\n```\n\n### Patent Artifact Routing\n\n| Artifact | Path | Purpose |\n|----------|------|---------|\n| Filing drafts | `docs/patents/SP-NNN/` | Specification, claims, filing guide |\n| Mining candidates | `ShadowArchive/10-projects/patent-queue/` | Candidate queue JSON |\n| Obsidian dossiers | Obsidian vault | Filing review notes |\n| Portfolio README | `docs/patents/README.md` | Auto-generated index |\n\n资料来源：[skills/patent-queue/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/patent-queue/SKILL.md), [skills/shadow-patent-factory/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-patent-factory/SKILL.md)\n\n---\n\n## Skill Development Framework\n\n### SKILL.md Template Structure\n\n```yaml\n---\nname: skill-name\ndescription: Brief description. Use when [specific triggers].\n---\n\n# Skill Name\n\n## Quick start\n[Minimal working example]\n\n## Workflows\n[Step-by-step processes]\n\n## Advanced features\n[References to separate files]\n```\n\n### Description Requirements\n\n- Maximum 1024 characters\n- Third person perspective\n- First sentence: what it does\n- Second sentence: when/triggers to use it\n\n**Good example:**\n> Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.\n\n资料来源：[skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n\n### Crystallization Process\n\nThe `crystallize` skill extracts patterns from AI sessions:\n\n1. **Identify** — recognize valuable session patterns\n2. **Draft** — create new skill or extend existing\n3. **Log** — record metadata under `## Crystallized From`\n\n```markdown\n## Crystallized From\n- Session: [date/context]\n- Original task: [what was being solved]\n- Pattern extracted: [description]\n```\n\n资料来源：[skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n---\n\n## Artifact Routing System\n\n### Global Artifact Paths\n\n| Artifact Type | Path | Purpose |\n|---------------|------|---------|\n| Reports | `ShadowArchive/80-reports/` | Session summaries, scan results |\n| Refactor signals | `tools/integrate/tool-signals.jsonl` | Per-fix JSONL results |\n| Agent roots | `ShadowArchive/03-agent-roots/` | Agent configuration |\n| Registry | `ShadowArchive/01-registry/` | Central registry |\n| System controls | `system/controls/` or `config/system/` | Configuration changes |\n\n### Output Rules by Layer\n\n| Output Type | Format | Location |\n|-------------|--------|----------|\n| User-facing docs | Concise, structured markdown | Standard output |\n| Machine-readable | YAML/JSON first | Canonical maps |\n| Runtime scaffolds | Minimal but real | config/code |\n| Skills | Reusable patterns | Skill directories |\n\n资料来源：[skills/shadow-continuity/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-continuity/SKILL.md)\n\n---\n\n## Promotion Levels\n\nArtifacts flow through maturity levels:\n\n```mermaid\ngraph TD\n    A[Note] --> B[Canonical Map]\n    B --> C[Skill]\n    C --> D[Runtime]\n    \n    A1[docs/plans/] --> A\n    B1[YAML/JSON] --> B\n    C1[~/.agents/skills/] --> C\n    D1[Scaffold/Config] --> D\n```\n\n| Level | Storage | Authority |\n|-------|---------|-----------|\n| 1 - Note | `docs/plans/` or reports | Useful but not authoritative |\n| 2 - Canonical Map | YAML/JSON files | Machine-readable truth |\n| 3 - Skill | `~/.agents/skills/` | Reusable operator behavior |\n| 4 - Runtime | Scaffold/config/code | Actually consumed by system |\n\n资料来源：[skills/shadow-continuity/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-continuity/SKILL.md)\n\n---\n\n## Technical Standards\n\n### AI SDK v5 Changes Reference\n\nThe `ai-sdk-core/references/v5-breaking-changes.md` documents breaking changes for Vercel AI SDK v5:\n\n| Change | v4 | v5 |\n|--------|----|----|\n| Schema import | `zodSchema` | `tool` |\n| Message types | `CoreMessage`, `Message` | `ModelMessage`, `UIMessage` |\n| Error handling | `ToolExecutionError` | Regular errors as content parts |\n\n资料来源：[skills/ai-sdk-core/references/v5-breaking-changes.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/v5-breaking-changes.md)\n\n---\n\n## Getting Started\n\n### Loading Skills\n\nAI agents automatically load skills based on trigger phrases in the user's request. Each skill's `description` field contains the triggers that activate it.\n\n### Prerequisites\n\n| Skill Category | Required Access |\n|----------------|------------------|\n| Shadow infrastructure skills | SHADOW infrastructure accessible |\n| Mesh skills | Tailscale mesh connected |\n| Patent skills | `auto-patent` CLI installed |\n| Engineering skills | Caresoft API access |\n| Local AI skills | Ollama running on localhost:11434 |\n\n### Verification Commands\n\n```bash\n# Check Ollama availability\ncurl -s http://localhost:11434/api/tags | head -1\n\n# Verify Shadow infrastructure\nnpm run verify:portable\n\n# Run patent tests\ncd auto-patent && node --test tests/*.test.js\n```\n\n---\n\n## Related Documentation\n\n- [Shadow Enterprise Architecture](skills/codex-context/SKILL.md)\n- [Refactoring Best Practices](skills/shadow-refactor/SKILL.md)\n- [Patent Filing Guide](skills/shadow-patent-factory/SKILL.md)\n- [Multi-Model Synthesis](skills/multi-model-query/SKILL.md)\n- [AI SDK Reference](skills/ai-sdk-core/references/v5-breaking-changes.md)\n\n---\n\n<a id='installation'></a>\n\n## Installation Guide\n\n### 相关页面\n\n相关主题：[Home - Repository Overview](#home), [Skill Dependencies & Metadata](#skill-dependencies)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/package.json)\n- [scripts/install.js](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/scripts/install.js)\n- [skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)\n- [skills/shadow-mcp-gadgets/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mcp-gadgets/SKILL.md)\n- [skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n- [skills/qmd-memory/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/qmd-memory/SKILL.md)\n</details>\n\n# Installation Guide\n\n## Overview\n\nThis repository (`s4b7-ai-skills`) is a collection of AI agent skills designed to extend the capabilities of various AI systems including Codex, Claude, Gemini, and local models via Ollama. Each skill is a self-contained module that provides specific functionality, from code refactoring to patent generation.\n\nThe installation process involves setting up the skill framework, configuring skill dependencies, and verifying that skills are properly registered and accessible to your AI agents. Skills are defined using YAML frontmatter in `SKILL.md` files with accompanying scripts and references.\n\n## Prerequisites\n\n### System Requirements\n\n| Component | Minimum | Recommended |\n|-----------|---------|-------------|\n| Node.js | 18.x | 20.x+ |\n| npm | 8.x | 10.x+ |\n| Git | 2.x | Latest |\n| Disk Space | 100MB | 500MB |\n\n### Required Tools\n\nBefore installing skills, ensure the following tools are available:\n\n- **Git** — Required for cloning repositories and version control operations 资料来源：[skills/shadow-refactor/SKILL.md:25]()\n- **pytest/vitest/jest** — Test runners for verifying skill functionality 资料来源：[skills/shadow-refactor/SKILL.md:26]()\n- **curl** — For checking local model availability (Ollama) 资料来源：[skills/shadow-refactor/SKILL.md:23]()\n\n### External Services (Optional)\n\n| Service | Purpose | Configuration |\n|---------|---------|---------------|\n| Ollama | Local LLM inference | `http://localhost:11434` |\n| Tailscale | Mesh networking | Mesh nodes required |\n| MCP Servers | Tool integrations | Per-skill configuration |\n\n## Installation Steps\n\n### Step 1: Clone the Repository\n\n```bash\ngit clone https://github.com/s4b7-ai/s4b7-ai-skills.git\ncd s4b7-ai-skills\n```\n\n### Step 2: Install Dependencies\n\nRun the installation script to set up the skill framework:\n\n```bash\nnpm install\n```\n\nThis will install all required npm dependencies and prepare the skill infrastructure for use. The `package.json` defines the project dependencies and scripts available for skill management.\n\n### Step 3: Configure Skill Paths\n\nSkills are organized in a directory structure that AI agents traverse when loading capabilities. The default skill locations are:\n\n| Location Type | Path | Purpose |\n|---------------|------|---------|\n| First-party | `/Volumes/☯Duality/skills/` | Primary skill collection |\n| Vendor | `/Volumes/☯Duality/.agents/skills/` | Vendor-provided skills |\n| User | `/Volumes/☯Duality/.pi/skills/` | Personal skill customizations |\n| Project-level | `.agents/skills/` | Project-specific skills |\n\nEnsure your AI agent's configuration points to one or more of these directories. For Codex integration, configure `~/.codex/config.toml` with the appropriate skill paths.\n\n### Step 4: Verify Portability\n\nCheck that all skill symlinks and references are valid:\n\n```bash\nnpm run verify:portable\n```\n\nThis command validates that skills can be loaded correctly from their configured paths.\n\n## Skill Structure\n\nEach skill follows a standardized structure:\n\n```\nskill-name/\n├── SKILL.md          # Main skill definition with YAML frontmatter\n├── REFERENCE.md      # Detailed reference documentation (optional)\n├── scripts/          # Utility scripts (optional)\n│   └── helper.js\n└── tests/            # Test files (optional)\n    └── skill.test.js\n```\n\n### SKILL.md Format\n\nEvery skill requires a `SKILL.md` file with this frontmatter structure:\n\n```yaml\n---\nname: skill-name\ndescription: Brief description. Use when [specific triggers].\n---\n```\n\n**Description Requirements:**\n- Maximum 1024 characters\n- Written in third person\n- First sentence: what it does\n- Second sentence: when to trigger it (specific keywords, contexts, file types)\n\n**Good example:**\n```\nExtract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.\n```\n\n资料来源：[skills/write-a-skill/SKILL.md:45-52]()\n\n## CLI Commands\n\n### qmd-memory (Memory Management)\n\n| Command | Description |\n|---------|-------------|\n| `qmd-memory store \"text\" --kind fact --tag work` | Store a memory item |\n| `qmd-memory recall` | List all memories |\n| `qmd-memory recall --kind fact` | Filter by kind |\n| `qmd-memory extract notes.md --source-id \"file:notes.md\"` | Extract from file |\n| `qmd-memory profile` | Show user profile |\n\nMemory kinds: `fact`, `commitment`, `decision`, `preference`, `context`\n\n资料来源：[skills/qmd-memory/SKILL.md:20-40]()\n\n### shadow-patents (Patent Generation)\n\n| Command | Description |\n|---------|-------------|\n| `shadow-patents list` | List portfolio |\n| `shadow-patents status` | Filing readiness dashboard |\n| `shadow-patents show SP-025` | Detailed view |\n| `shadow-patents create \"Title\"` | Scaffold new patent |\n| `shadow-patents register SP-025` | Add to registry |\n\n资料来源：[skills/shadow-patent-factory/SKILL.md:85-95]()\n\n### upscaler (Command Center)\n\n| Command | Description |\n|---------|-------------|\n| `npm run upscaler_action_read` | Review action drafts |\n| `npm run upscaler_actions` | List all actions |\n| `upscaler_draft` MCP tool | Generate SCAR notification |\n| `upscaler_tune mode: status` | Check tuning metrics |\n| `upscaler_tune mode: run` | Full tuning cycle |\n\nDashboard access:\n- **FRIDAY**: http://friday-mac:3333/\n- **Local**: `cd ~/wip/ai-at-work && ./bin/upscaler dashboard`\n\n资料来源：[skills/command-center/SKILL.md:45-65]()\n\n## MCP Server Integration\n\nThe repository supports multiple MCP (Model Context Protocol) servers for extended functionality:\n\n| MCP Server | Path | Purpose |\n|------------|------|---------|\n| RepoPrompt | `/Users/sdluffy/RepoPrompt/repoprompt_cli` | Repository intelligence |\n| chrome_devtools | `/Users/sdluffy/bin/chrome-devtools-mcp-work` | Browser automation |\n| notion | `https://mcp.notion.com/mcp` | Notion integration |\n| openevidence | `node .../openevidence-mcp/dist/server.js` | Evidence management |\n| playwright | `/Users/sdluffy/bin/playwright-mcp-work` | Web testing |\n\n资料来源：[skills/codex-context/SKILL.md:25-32]()\n\n## Gadget System\n\nThe shadow-mcp-gadgets skill provides a unified interface to various subsystems:\n\n| Gadget | Trigger | Purpose |\n|--------|---------|---------|\n| ARC | `arc.store`, `arc.search` | Memory storage and retrieval |\n| ESP | `esp.assemble`, `/renew-ctx` | Context assembly |\n| ANT | `ant.mesh` | Fleet health via Tailscale |\n| TAP | `tap.tabs`, `tap.execute` | Chrome tabs + JavaScript |\n| OWL | `owl.brief`, `owl.extract` | Bee AI extraction |\n| ORB | `orb.say`, `orb.voices` | macOS TTS |\n| DEN | `den.environment` | Physical sensors |\n| Factory | `factory.new`, `factory.draft` | Patent pipeline |\n\nIf the MCP federation server is not running, start it via:\n```bash\nbun run /Volumes/SHADOW/shadow-lab/apps/shadow-mcp\n```\n\n资料来源：[skills/shadow-mcp-gadgets/SKILL.md:20-35]()\n\n## Auto-Delegation Configuration\n\nThe `acp-delegate-auto` skill routes tasks to appropriate AI providers based on content analysis:\n\n### Routing Heuristics\n\n| If prompt contains... | Route to |\n|----------------------|----------|\n| `write`, `implement`, `refactor`, `debug code` | codex |\n| `research`, `summarize`, `find`, `compare` | gemini |\n| `translate`, `JP`, `Japanese` | Codex |\n| `local`, `private`, `no cloud` | ollama |\n| `review`, `architect`, `design` | Codex |\n| `quickly`, `fast`, `brief` | ollama |\n| file paths, diffs, PRs | codex |\n\n### Provider Configuration\n\n```bash\n# Qwen3 (Ollama): prepend /no_think to prompt\n# Codex: use mcp__codex__codex tool with workdir set\n\n# Gemini via OpenRouter:\n# - Speed: google/gemini-2.0-flash-001\n# - Depth: google/gemini-2.5-pro\n\n# Codex via ACP:\n# - Default: Codex-sonnet-4-6\n# - Complex: Codex-opus-4-6\n```\n\n资料来源：[skills/acp-delegate-auto/SKILL.md:15-40]()\n\n## Verification\n\nAfter installation, verify your setup:\n\n### 1. Check Skill Loading\n\n```bash\n# List all available skills\nls skills/*/SKILL.md\n```\n\n### 2. Test Skill Execution\n\n```bash\n# Run skill validation tests\ncd auto-patent && node --test tests/*.test.js\n```\n\nAll tests should pass. For patent-related skills, ensure all 44 auto-patent tests pass before considering the installation complete.\n\n### 3. Verify Agent Configuration\n\nEnsure your AI agent's configuration file (e.g., `~/.codex/config.toml` for Codex) references the correct skill directories.\n\n## Troubleshooting\n\n### Symlink Failures\n\nIf portability verification fails, check symlink integrity:\n```bash\nnpm run verify:portable\n```\n\n### Skill Not Loading\n\n1. Verify the `SKILL.md` file has valid YAML frontmatter\n2. Check that the skill directory is in the agent's search path\n3. Ensure description includes proper trigger keywords\n\n### MCP Server Connection Issues\n\nIf gadgets are unavailable, start the shadow-mcp federation server:\n```bash\nbun run /Volumes/SHADOW/shadow-lab/apps/shadow-mcp\n```\n\n### Ollama Not Responding\n\nCheck if Ollama is running:\n```bash\ncurl -s http://localhost:11434/api/tags | head -1\n```\n\nIf unavailable, the system falls back to static analysis mode using grep, AST, and file metrics.\n\n## Skill Surgery & Maintenance\n\nFor managing existing skills:\n\n| Operation | Purpose |\n|-----------|---------|\n| Audit skills | `audit-skills.mjs` — inventory all skills |\n| Cluster triggers | `cluster-skill-triggers.mjs` — analyze trigger patterns |\n| Redirect deprecated | `redirect-deprecated-skill.mjs` — handle outdated skills |\n\n**Important Rules:**\n- Never delete skills during exploratory surgery; redirect instead\n- Circular redirects (A → B → A) must be blocked and reported\n- Preserve operator-specific boundaries when consolidating enterprise skills\n\n资料来源：[skills/skill-surgery-rd/SKILL.md:30-45]()\n\n## Related Documentation\n\n- [Write a Skill Guide](skills/write-a-skill/SKILL.md) — How to create new skills\n- [Shadow Refactor](skills/shadow-refactor/SKILL.md) — Code analysis and refactoring\n- [Memory System](skills/qmd-memory/SKILL.md) — Persistent agent memory\n- [Codex Context](skills/codex-context/SKILL.md) — Codex integration details\n- [A2A Orchestrator](skills/a2a-orchestrator/SKILL.md) — Multi-agent orchestration\n\n---\n\n<a id='skill-structure'></a>\n\n## Skill Structure & Anatomy\n\n### 相关页面\n\n相关主题：[Home - Repository Overview](#home), [Write A Skill - Authoring Guide](#write-a-skill), [Skill Dependencies & Metadata](#skill-dependencies)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n- [skills/shadow-mcp-gadgets/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mcp-gadgets/SKILL.md)\n- [skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n- [skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n- [skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)\n- [skills/qmd-memory/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/qmd-memory/SKILL.md)\n</details>\n\n# Skill Structure & Anatomy\n\n## Overview\n\nA **Skill** is a reusable capability module that encapsulates domain-specific knowledge, workflows, and decision-making patterns for an AI agent. Skills enable agents to perform specialized tasks by providing structured guidance on when and how to apply particular capabilities.\n\nSkills serve as the atomic unit of agentic capability—each skill contains sufficient information for an agent to recognize when it should be invoked and how to execute the associated workflow. The skill system supports a modular architecture where skills can be composed, extended, and shared across different agent contexts.\n\n## Core Anatomy of a Skill\n\nEvery skill is fundamentally defined by its metadata and operational content. The minimal viable skill consists of YAML frontmatter and a Markdown body that describes the capability.\n\n### YAML Frontmatter\n\nThe frontmatter uses a standardized schema to ensure parsers and agents can reliably extract skill metadata:\n\n```yaml\n---\nname: skill-name\ndescription: Brief description of capability. Use when [specific triggers].\n---\n```\n\n**Required Fields:**\n\n| Field | Type | Purpose | Constraints |\n|-------|------|---------|-------------|\n| `name` | string | Unique identifier for the skill | Lowercase, hyphenated |\n| `description` | string | Triggers and summary for agent selection | Max 1024 chars, third person, must include \"Use when...\" |\n\n**Description Format Requirements:**\n\nThe description serves as the primary signal for skill routing. It must:\n\n1. Start with a first sentence describing what the skill does\n2. Include a second sentence beginning with \"Use when...\" followed by specific trigger phrases\n3. Be written in third person\n4. Be concise enough for the agent to quickly evaluate relevance\n\n**Good Example:**\n```\nExtract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.\n```\n\n**Poor Example:**\n```\nHelps with documents.\n```\n\n资料来源：[skills/write-a-skill/SKILL.md:47-56]()\n\n### Markdown Body Structure\n\nThe SKILL.md file contains the operational content organized into logical sections:\n\n```markdown\n# Skill Name\n\nOne-line description. Use when [trigger phrases].\n\n## When to Use\n- [trigger 1]\n- [trigger 2]\n- [trigger 3]\n\n## Workflow\n1. [Step 1]\n2. [Step 2]\n3. [Step 3]\n\n## Key Decisions\n- [Decision point 1]: [default choice + why]\n- [Decision point 2]: [default choice + why]\n\n## Gotchas\n- [Common mistake 1]\n- [Common mistake 2]\n\n## Crystallized From\n- Session: [date/context]\n- Original task: [what was being solved]\n```\n\n资料来源：[skills/crystallize/SKILL.md:1-24]()\n\n## Skill Directory Structure\n\nSkills follow a predictable directory layout that enables both human navigation and programmatic discovery:\n\n```\n~/.agents/skills/<skill-name>/\n├── SKILL.md              # Primary skill definition (REQUIRED)\n├── REFERENCE.md          # Extended reference documentation\n├── scripts/              # Utility scripts (if needed)\n│   └── helper.js\n└── docs/                 # Additional documentation\n    └── plans/\n        └── crystallization-log.md\n```\n\n**First-party skills** are located at `/Volumes/☯Duality/skills/`\n\n**Vendor skills** are located at `/Volumes/☯Duality/.agents/skills/`\n\n**Project-specific skills** follow the pattern `.agents/skills/` within the project root\n\n资料来源：[skills/codex-context/SKILL.md:12-18]()\n\n## Skill Lifecycle\n\n### Crystallization Mode\n\nThe primary mechanism for creating skills is **crystallization**—extracting reusable patterns from completed work sessions into structured skill definitions.\n\n```mermaid\ngraph TD\n    A[Ticket/Task Received] --> B[Session Work Begins]\n    B --> C{Task Complete?}\n    C -->|No| D[Continue Working]\n    D --> C\n    C -->|Yes| E{Should this recur?}\n    E -->|No| F[Done]\n    E -->|Yes| G[Review Session]\n    G --> H[Extract Pattern]\n    H --> I{Check Scope}\n    I --> J{Search existing skills}\n    J -->|Overlap found| K[Update Existing Skill]\n    J -->|No overlap| L[Create New Skill]\n    K --> M[Log Crystallization]\n    L --> M\n```\n\n**Crystallization Modes:**\n\n| Mode | Output | Trigger Phrases |\n|------|--------|-----------------|\n| `default` | Full crystallization workflow | `crystallize`, `capture this as a skill` |\n| `quick` | Fast capture to minimal stub | `quick crystallize`, mid-task pattern discovery |\n| `exploratory` | Expand one ring outward from fix | `--exploratory-mode`, `more crystallization` |\n| `drag-response` | Immediate crystallization | `this took too long`, `why aren't you using...` |\n| `correction` | Immediate update from operator | Operator corrects an identity/path/boundary |\n| `audit` | Check missed patterns | `what patterns did we miss` |\n\n资料来源：[skills/crystallize/SKILL.md:65-79]()\n\n### Exploratory-Mode Expansion\n\nWhen crystallizing in exploratory mode, the process expands beyond the immediate fix to capture broader patterns:\n\n1. Start from the exact thing that was fixed\n2. Check nearest adjacent surfaces that could carry the same pattern\n3. Capture the broader reusable rule\n4. Log what surfaces were checked and which were intentionally left untouched\n\n## Skill Components\n\n### Workflow Section\n\nThe workflow section defines the step-by-step process for executing the skill. Each workflow should:\n\n- Start with the minimal steps required\n- Include decision points as checkpoints\n- Provide clear success criteria\n- Be deterministic enough for reliable execution\n\n**Workflow Format:**\n\n```markdown\n## Workflow\n\n```dot\ndigraph workflow_name {\n  rankdir=TB;\n  \"Start\" -> \"Step 1\" -> \"Step 2\" -> \"Decision Point\" -> \"End\"\n  \"Decision Point\" -> \"Alt Path A\" [label=\"Condition A\"]\n  \"Decision Point\" -> \"Alt Path B\" [label=\"Condition B\"]\n}\n```\n\n### Decision Points\n\nCritical decision points should be documented with:\n\n- The decision context\n- Available options\n- Default choice and rationale\n- When to deviate from default\n\n**Decision Point Format:**\n\n```markdown\n## Key Decisions\n\n- [Decision point 1]: [default choice + why]\n- [Decision point 2]: [default choice + why]\n```\n\n### Gotchas Section\n\nThe gotchas section captures lessons learned from real usage:\n\n- Common mistakes that cause failures\n- Assumptions that often fail\n- Edge cases requiring special handling\n- Configuration traps\n\n## Skill Routing and Invocation\n\n### Routing Heuristics\n\nSkills are selected based on trigger detection in the agent's context. The routing system uses keyword matching against skill descriptions:\n\n| If prompt contains... | Route to |\n|----------------------|----------|\n| `write`, `implement`, `refactor`, `debug code` | codex |\n| `research`, `summarize`, `find`, `compare` | gemini |\n| `translate`, `JP`, `Japanese` | Codex |\n| `local`, `private`, `no cloud` | ollama |\n| `review`, `architect`, `design` | Codex |\n| `quickly`, `fast`, `brief` | ollama |\n| file paths, diffs, PRs | codex |\n\n资料来源：[skills/acp-delegate-auto/SKILL.md:24-35]()\n\n### Trigger Phrase Format\n\nSkill descriptions must include trigger phrases in the \"Use when...\" section:\n\n```markdown\n## When to Use\n- [trigger 1]\n- [trigger 2]\n- [trigger 3]\n```\n\nThese triggers are matched against incoming agent context to determine skill relevance.\n\n## Skill Validation and Quality\n\n### Review Checklist\n\nBefore finalizing a skill, verify:\n\n- [ ] Description includes triggers (\"Use when...\")\n- [ ] SKILL.md under 100 lines\n- [ ] No time-sensitive info (no dates, version numbers that will stale)\n- [ ] Consistent terminology throughout\n- [ ] Concrete examples included\n- [ ] References one level deep (no deep-linking to unrelated docs)\n\n资料来源：[skills/write-a-skill/SKILL.md:85-91]()\n\n### File Size Guidelines\n\n| Condition | Action |\n|-----------|--------|\n| SKILL.md exceeds 100 lines | Split into separate files |\n| Content has distinct domains | Split into domain-specific files |\n| Advanced features are rarely needed | Reference separate REFERENCE.md |\n| Content is deterministic/formatting | Add utility scripts instead |\n\n资料来源：[skills/write-a-skill/SKILL.md:74-81]()\n\n## Skill Surgery and Maintenance\n\n### When to Perform Surgery\n\nSkills require maintenance when:\n\n- Overlapping capabilities exist across multiple skills\n- Triggers become stale or misaligned with actual usage\n- Skills grow too large (violates 100-line guideline)\n- Domain boundaries shift requiring re-organization\n\n### Surgery Operations\n\n| Operation | Purpose | Command Pattern |\n|-----------|---------|-----------------|\n| `audit` | Inventory all skills and their triggers | `skill_audit` |\n| `cluster` | Group skills by trigger overlap | `cluster-skills` |\n| `redirect` | Move deprecated skill to canonical location | `redirect-deprecated-skill` |\n\n### Redirect Chain\n\nWhen a skill is deprecated:\n\n1. Do not delete the old skill\n2. Create redirect metadata pointing to canonical location\n3. Log the redirect for audit trail\n4. Update any skills that reference the deprecated path\n\n**Contract:** Do not delete skills during exploratory surgery. Redirect first; deletion requires explicit operator approval after review.\n\n资料来源：[skills/skill-surgery-rd/SKILL.md:67-73]()\n\n## Artifact Routing\n\nSkills generate artifacts that follow a consistent routing pattern:\n\n| Artifact Type | Path Pattern | Purpose |\n|---------------|--------------|---------|\n| New skill | `~/.agents/skills/<slug>/SKILL.md` | Reusable capability |\n| Updated skill | Same path as existing skill | Extended capability |\n| Crystallization log | `docs/plans/crystallization-log.md` | History of all crystallizations |\n| Reports | `ShadowArchive/80-reports/` | Session summaries |\n| Tool signals | `tools/integrate/tool-signals.jsonl` | Per-fix results |\n\n资料来源：[skills/crystallize/SKILL.md:80-91]()\n\n## Integration with Agent Memory\n\nSkills can be integrated with persistent memory systems:\n\n### Memory Kinds\n\n| Kind | Purpose | Example |\n|------|---------|---------|\n| `fact` | Permanent facts | \"TypeScript is the primary language\" |\n| `commitment` | Future tasks | \"Need to finish setup by Friday\" |\n| `decision` | Choices made | \"Decided to use local-first\" |\n| `preference` | User preferences | User prefers dark mode |\n| `context` | Session context | Current project state |\n\n### Memory Extraction Pipeline\n\nSkills can trigger memory extraction through the `qmd-memory` interface:\n\n```bash\n# Extract from text\nqmd-memory extract notes.md --source-id \"file:notes.md\"\n\n# From piped data\nbee conversations get <id> --json | jq -r '.summary' | qmd-memory extract - --source-id \"bee:conv:<id>\"\n```\n\n资料来源：[skills/qmd-memory/SKILL.md:1-35]()\n\n## Multi-Model Skill Distribution\n\nSkills can delegate execution to specialized models based on task requirements:\n\n```mermaid\ngraph LR\n    A[Intent] --> B{Route Decision}\n    B -->|Code| C[Codex]\n    B -->|Research| D[Gemini]\n    B -->|Local| E[Ollama]\n    B -->|Synthesis| F[Multi-Model]\n    C --> G[Execute]\n    D --> G\n    E --> G\n    F --> G\n```\n\n### Provider-Specific Preparation\n\nBefore delegating, apply model-specific transforms:\n\n| Provider | Transform |\n|----------|-----------|\n| `qwen3` (any Ollama model) | Prepend `/no_think` to prompt or set `options.think = false` |\n| `codex` (mcp) | Use `mcp__codex__codex` tool with workdir set to current project |\n| `gemini` (openrouter) | Use `google/gemini-2.0-flash-001` for speed, `google/gemini-2.5-pro` for depth |\n| `Codex` (ACP anthropic) | Use `Codex-sonnet-4-6` default, `Codex-opus-4-6` for complex tasks |\n\n## Fallback Chain Pattern\n\nRobust skills implement a fallback chain for resilience:\n\n```\n1. Primary: Full scan/operation\n2. Degraded: Local paths only\n3. Offline: Skip unreachable, continue with available\n4. API unavailable: Report; proceed with manual or cached\n5. Empty: Report; note likely path issue\n6. Last resort: Minimal coverage with explicit statement of degradation\n```\n\nEach failure mode should have a documented recovery action that allows the skill to continue or gracefully report inability.\n\n## Relationship to Agent Infrastructure\n\n### Skill Discovery Order\n\nFor context-based skills, the read order defines precedence:\n\n1. `/Volumes/☯Duality/AGENTS.md` — master control surface\n2. `reference/SHADOW-CONTEXT.md` — quick paths and fleet\n3. `reference/ARCHITECTURE.md` — layered architecture\n4. `reference/SHADOW-ARCHITECTURE-SPEC.md` — full spec\n5. `reference/VERIFIABILITY.md` — proof-of-work rules\n6. `docs/reference/SHADOW-DUALITY-ORGANIZATION.md` — rings + artifact resolution\n\n### Skills Namespace\n\nAll skills feed into the same namespace regardless of origin:\n\n- **First-party:** `/Volumes/☯Duality/skills/`\n- **Vendor:** `/Volumes/☯Duality/.agents/skills/`\n- **Project-specific:** `.agents/skills/`\n- **Enterprise:** Appropriate subdirectory under `~/.agents/skills/`\n\nThis unified namespace allows agents to discover and invoke any skill regardless of its origin point.\n\n## Best Practices Summary\n\n1. **Trigger Clarity:** Always include \"Use when...\" clause with specific trigger phrases\n2. **Size Discipline:** Keep SKILL.md under 100 lines; extract to REFERENCE.md for extended content\n3. **Deterministic Scripts:** Use utility scripts for repetitive, predictable operations\n4. **Crystallization Logging:** Record session date, context, and pattern extracted\n5. **No Stale Data:** Avoid version numbers, pricing, or API shapes that will become outdated\n6. **Preserve History:** Never delete skills; redirect deprecated ones\n7. **Single Responsibility:** One skill = one capability; split when domains diverge\n8. **Citation:** Reference source patterns when extracting from other skills\n\n---\n\n<a id='skill-dependencies'></a>\n\n## Skill Dependencies & Metadata\n\n### 相关页面\n\n相关主题：[Skill Structure & Anatomy](#skill-structure), [Crystallize - Pattern Extraction](#crystallize)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n- [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n- [skills/shadow-engg/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-engg/SKILL.md)\n- [skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)\n- [skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n- [skills/qmd-memory/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/qmd-memory/SKILL.md)\n- [skills/shadow-mcp-gadgets/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mcp-gadgets/SKILL.md)\n</details>\n\n# Skill Dependencies & Metadata\n\n## Overview\n\nThe s4b7-ai-skills repository implements a structured approach to skill documentation that encompasses metadata standards, dependency management, and artifact routing. Each skill follows a consistent SKILL.md template that defines its purpose, trigger conditions, workflows, and integration points with other system components.\n\nThe metadata system serves three core purposes: enabling agent-based skill selection through descriptive frontmatter, establishing clear execution workflows with fallback chains, and routing artifacts to appropriate storage locations for persistence and retrieval.\n\n## Skill Metadata Structure\n\n### Frontmatter Schema\n\nEvery skill in the repository begins with YAML frontmatter that defines its identity and selection criteria. The required metadata fields ensure proper agent routing and discovery.\n\n| Field | Purpose | Constraints |\n|-------|---------|-------------|\n| `name` | Skill identifier | Unique within skill namespace |\n| `description` | Capability summary for agent selection | Max 1024 chars, third person, must include \"Use when...\" clause |\n| `triggers` | Keywords and contexts that activate the skill | Extracted from description for matching |\n\n资料来源：[skills/write-a-skill/SKILL.md:1-20]()\n\n### Description Requirements\n\nThe description field is the primary mechanism by which agents decide which skill to load. It must follow a strict two-sentence format:\n\n1. **First sentence**: States what the skill does\n2. **Second sentence**: Contains the \"Use when...\" clause specifying trigger conditions\n\nExample of a well-formed description:\n\n```\nExtract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.\n```\n\n资料来源：[skills/write-a-skill/SKILL.md:52-56]()\n\nThe description is surfaced in the system prompt alongside all other installed skills, allowing the agent to pick the relevant skill based on the user's request. This makes the description the single most important metadata element for skill discoverability.\n\n### Skill Kinds and Tags\n\nThe `qmd-memory` skill implements a tagging system for memory classification that can be applied to skill metadata:\n\n| Kind | Usage |\n|------|-------|\n| `fact` | Permanent factual information |\n| `commitment` | Promises or obligations |\n| `decision` | Choices made during execution |\n| `preference` | User or system preferences |\n| `context` | Session-specific context |\n\nTags provide additional dimension to skill metadata, enabling filtering and targeted recall.\n\n资料来源：[skills/qmd-memory/SKILL.md:45-52]()\n\n## Skill Modes and Command Routing\n\n### Mode Architecture\n\nSkills expose multiple operational modes that define different execution paths. The mode system allows a single skill to handle diverse use cases through command-based routing.\n\n```mermaid\ngraph TD\n    A[User Input] --> B{Mode Detection}\n    B -->|default| C[Standard Execution]\n    B -->|verbose| D[Detailed Diagnostics]\n    B -->|json| E[Machine Output]\n    B -->|background| F[Autonomous Loop]\n    \n    C --> G[Primary Handler]\n    D --> H[Debug Handler]\n    E --> I[Parse Handler]\n    F --> J[Background Agent]\n    \n    G --> K[Result Output]\n    H --> K\n    I --> K\n    J --> K\n```\n\n资料来源：[skills/codex-latex/SKILL.md:35-48]()\n\n### Mode Reference by Skill\n\n| Skill | Modes | Purpose |\n|-------|-------|---------|\n| `ai-sdk-core` | migrate, agent, error, workers, verify | AI SDK v5/v6 lifecycle management |\n| `shadow-engg` | explore, engineering | Competitive intelligence and gap analysis |\n| `shadow-refactor` | background, patterns, hotspot, equilibrium | Code refactoring and pattern extraction |\n| `shadow-mcp-gadgets` | memory, context, mesh, browser, ambient, voice, environment, patent, test | MCP tool delegation |\n\n资料来源：[skills/shadow-engg/SKILL.md:1-30](), [skills/shadow-refactor/SKILL.md:1-15](), [skills/shadow-mcp-gadgets/SKILL.md:1-20]()\n\n## Artifact Routing System\n\n### Artifact Types\n\nArtifacts are outputs produced during skill execution that require persistent storage. Each skill defines a routing table specifying where artifacts should be stored.\n\n| Artifact Type | Path Pattern | Purpose |\n|--------------|--------------|---------|\n| Tool signals | `tools/integrate/tool-signals.jsonl` | Per-fix results in JSONL format |\n| Refactor reports | `ShadowArchive/80-reports/refactor-<target>-YYYY-MM-DD.md` | Session summaries |\n| Memory stores | `ARC memory store` | Persistent agent memory |\n| Patent drafts | `docs/patents/SP-NNN/` | Specification and claims |\n\n资料来源：[skills/shadow-refactor/SKILL.md:15-22](), [skills/shadow-mcp-gadgets/SKILL.md:22-28]()\n\n### Artifact Routing Table Format\n\nSkills implement artifact routing through structured tables in SKILL.md:\n\n```\n| Artifact | Location | Purpose |\n|----------|----------|---------|\n| Code changes | Project files (inline) | Implementation output |\n| Detailed reference | `REFERENCE.md` (skill companion) | Migrations, errors, model notes |\n| Original backup | `data/skill-rd/active-split-backups/` | Pre-split archive |\n```\n\n资料来源：[skills/ai-sdk-core/SKILL.md:28-33]()\n\n## Fallback Chain Architecture\n\n### Fallback Principles\n\nEvery skill implements a fallback chain that defines recovery behavior when primary execution paths fail. The chain prioritizes available alternatives in order of preference.\n\n```mermaid\ngraph LR\n    A[Primary] --> B[Secondary]\n    B --> C[Tertiary]\n    C --> D[Last Resort]\n    \n    style A fill:#90EE90\n    style B fill:#FFE4B5\n    style C fill:#FFA07A\n    style D fill:#FF6B6B\n```\n\n### Fallback Chain Examples\n\n**ai-sdk-core Fallback Chain:**\n\n| Priority | Source | Condition |\n|----------|--------|-----------|\n| 1 | `REFERENCE.md` | Detailed reference available |\n| 2 | Web search / docs | REFERENCE.md stale or missing |\n| 3 | `npm view ai versions` | Version uncertainty |\n| 4 | Stable v5 default | All else fails |\n\n资料来源：[skills/ai-sdk-core/SKILL.md:35-42]()\n\n**shadow-engg Fallback Chain:**\n\n| Priority | Mode | Condition |\n|----------|------|-----------|\n| 1 | Full scan | ShadowArchive mounted, skills accessible |\n| 2 | Local-only | Archive unmounted |\n| 3 | Skip mesh health | Tailscale mesh unreachable |\n| 4 | Report API status | Caresoft API unavailable |\n\n资料来源：[skills/shadow-engg/SKILL.md:55-68]()\n\n**skill-surgery-rd Error Handling:**\n\n| Failure | Recovery |\n|---------|----------|\n| Script execution fails | Manual `find + grep` inventory |\n| Malformed YAML frontmatter | Flag; propose manual repair |\n| Circular redirect detected | Block; require manual resolution |\n| Too many skills (>500) | Prioritize active; sample archived |\n\n资料来源：[skills/skill-surgery-rd/SKILL.md:45-55]()\n\n## Skill Dependencies and Interconnections\n\n### Crystallization Workflow\n\nThe crystallization process creates dependencies between skills by extracting patterns from working sessions into reusable skill definitions.\n\n```mermaid\ngraph TD\n    A[Task Complete] --> B{Should this recur?}\n    B -->|yes| C[Review Session]\n    B -->|no| D[Done]\n    C --> E[Extract Pattern]\n    E --> F[Check Scope]\n    F --> G{Search Existing Skills}\n    G -->|overlap found| H[Update Existing]\n    G -->|no overlap| I[Create New Skill]\n    H --> J[Log Crystallization]\n    I --> J\n```\n\n资料来源：[skills/crystallize/SKILL.md:55-78]()\n\n### Exploratory-Mode Expansion\n\nWhen operators request expanded crystallization, the skill performs a broader sweep:\n\n1. Start from the exact thing that was fixed\n2. Check nearest adjacent surfaces that could carry the same stale assumption\n3. Capture the broader reusable rule\n\n资料来源：[skills/crystallize/SKILL.md:75-85]()\n\n### Skill Surgery and Dependencies\n\nThe `skill-surgery-rd` skill manages skill dependencies through audit and repair operations. Key operations include:\n\n- **Audit**: Scan skill directories for stale metadata, circular dependencies, or missing trigger conditions\n- **Merge**: Combine overlapping skills while preserving gotchas from both sources\n- **Redirect**: Route deprecated skill triggers to canonical replacements\n\n资料来源：[skills/skill-surgery-rd/SKILL.md:1-45]()\n\n## File Reference System\n\n### Global File Registry\n\nThe `codex-context` skill maintains a master file reference table for system-wide file access:\n\n| File | Purpose | Location |\n|------|---------|----------|\n| Codex config | Model, sandbox, MCP, plugins | `~/.codex/config.toml` |\n| Codex memories | Persistent memory across sessions | `~/.codex/memories/MEMORY.md` |\n| Codex rules | Caveman mode rules | `~/.codex/rules/*.md` |\n| Codex prompts | Will, swarm, review, skill-up | `~/.codex/prompts/*.md` |\n| Hermes SOUL.md | Shadow persona (default) | `~/.hermes/SOUL.md` |\n| Gemini GEMINI.md | YOLO mode + global rules | `~/.gemini/GEMINI.md` |\n\n资料来源：[skills/codex-context/SKILL.md:85-98]()\n\n### Key Path Resolution\n\n| Path Type | Location |\n|-----------|----------|\n| ShadowArchive | `/Volumes/☯Duality/ShadowArchive/` |\n| Reports | `ShadowArchive/80-reports/` |\n| Agent roots | `ShadowArchive/03-agent-roots/` |\n| Registry | `ShadowArchive/01-registry/` |\n| First-party skills | `/Volumes/☯Duality/skills/` |\n| Vendor skills | `/Volumes/☯Duality/.agents/skills/` |\n\n资料来源：[skills/codex-context/SKILL.md:35-48]()\n\n## Contract and Constraints\n\n### Skill Contracts\n\nEach skill defines a contract specifying operational boundaries:\n\n| Contract Element | Description |\n|-----------------|-------------|\n| Context persistence | Do not persist without operator request |\n| Zone boundaries | Enterprise context does not leak into personal zone |\n| Recall confidence | Always label confidence level |\n| Memory writes | Append-only, never destructive |\n\n资料来源：[skills/shadow-mind/SKILL.md:75-85]()\n\n### Operational Rules\n\n**skill-surgery-rd Contract:**\n\n- Do not delete skills during exploratory surgery — redirect first\n- Do not edit archived history unless surfacing as active trigger problem\n- Do not create giant omnibus skills — prefer canonical router plus focused subskills\n- Research before invention — never crystallize stale version numbers without freshness note\n\n资料来源：[skills/skill-surgery-rd/SKILL.md:57-70]()\n\n**shadow-engg Contract:**\n\n- Never modify production config without operator confirmation\n- Report all changes with before/after diff\n- Preserve existing configurations with backup\n\n资料来源：[skills/shadow-engg/SKILL.md:125-130]()\n\n## Integration with MCP Gadgets\n\n### Gadget Mode Routing\n\nThe `shadow-mcp-gadgets` skill routes commands to specialized tools based on trigger phrases:\n\n| Mode | Gadget | Triggers |\n|------|--------|----------|\n| `memory` | ARC | `arc.store`, `arc.search`, memory triggers |\n| `context` | ESP | `esp.assemble`, `/renew-ctx` |\n| `mesh` | ANT | `ant.mesh`, mesh health |\n| `browser` | TAP | `tap.tabs`, `tap.execute` |\n| `ambient` | OWL | `owl.brief`, `owl.extract` |\n| `voice` | ORB | `orb.say`, `orb.voices` |\n| `environment` | DEN | `den.environment` |\n| `patent` | Factory | `factory.new`, `factory.draft` |\n\n资料来源：[skills/shadow-mcp-gadgets/SKILL.md:8-18]()\n\n## Recall Scoring System\n\nThe `shadow-mind` skill implements confidence-based recall for skill metadata:\n\n| Confidence Level | Meaning | Source |\n|-----------------|---------|--------|\n| **Confirmed** | Found in durable artifact (anchor, kernel, Dropbox) | File match |\n| **Likely** | Found in training pairs or distilled experience | Pattern match |\n| **Inferred** | Reconstructed from context but no explicit artifact | Reasoning |\n| **Unknown** | No evidence found | No match |\n\nAlways label recall confidence. Never present inferred as confirmed.\n\n资料来源：[skills/shadow-mind/SKILL.md:55-65]()\n\n## Review Checklist\n\nAfter drafting or updating skill metadata, verify:\n\n- [ ] Description includes \"Use when...\" trigger clause\n- [ ] SKILL.md under 100 lines (split if exceeded)\n- [ ] No time-sensitive info that will become stale\n- [ ] Consistent terminology with adjacent skills\n- [ ] Concrete examples included\n- [ ] References one level deep only\n\n资料来源：[skills/write-a-skill/SKILL.md:95-102]()\n\n---\n\n<a id='langgraph-agent'></a>\n\n## LangGraph Agent Development\n\n### 相关页面\n\n相关主题：[AI SDK Core - Vercel Integration](#ai-sdk-core), [Agent Crystallization Protocol](#agent-cryst)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/langgraph-agent/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/langgraph-agent/SKILL.md)\n- [skills/langgraph-agent/references/advanced-patterns.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/langgraph-agent/references/advanced-patterns.md)\n\n**Note:** The specified source files were referenced in the query but were not included in the retrieved context. This wiki page is generated using standard LangGraph patterns and conventions consistent with the repository's skill documentation style.\n\n</details>\n\n# LangGraph Agent Development\n\n## Overview\n\nLangGraph Agent Development provides a framework for building stateful, multi-agent applications using LangGraph's graph-based architecture. It enables developers to create agents that maintain context across interactions, coordinate multiple sub-agents, and handle complex workflow orchestration through explicit state management and conditional routing.\n\nLangGraph extends the concept of LLM chains by introducing nodes (agents/tools) and edges (transitions) within a directed graph structure, allowing for more sophisticated agentic behaviors than linear chain implementations.\n\n## Core Concepts\n\n### Graph Architecture\n\nLangGraph applications are built as stateful graphs composed of nodes and edges:\n\n| Component | Description | Role in Architecture |\n|-----------|-------------|---------------------|\n| **State** | Shared data structure passed between nodes | Centralized memory model |\n| **Nodes** | Functions representing agents or tools | Execute tasks, modify state |\n| **Edges** | Define transitions between nodes | Control flow logic |\n| **Conditional Edges** | Dynamic routing based on state | Decision-making paths |\n\n### State Management\n\nState in LangGraph is typically a TypedDict or Pydantic model that accumulates data as it flows through the graph:\n\n```python\nfrom typing import TypedDict\nfrom typing_extensions import Annotated\nimport operator\n\nclass AgentState(TypedDict):\n    messages: Annotated[list, operator.add]\n    context: dict\n    next_action: str\n```\n\nThe `Annotated` type with `operator.add` enables message accumulation, where each node appends to the messages list rather than replacing it.\n\n## Workflow Patterns\n\n### Basic Agent Loop\n\n```mermaid\ngraph TD\n    A[User Input] --> B[LLM Decision Node]\n    B --> C{Should Respond?}\n    C -->|Yes| D[Return to User]\n    C -->|No| E{Should Use Tool?}\n    E -->|Yes| F[Execute Tool]\n    E -->|No| G[Continue to Next Node]\n    F --> H[Update State]\n    H --> B\n    G --> I[End or Next Agent]\n    I --> D\n```\n\n### Multi-Agent Orchestration\n\nFor complex tasks, LangGraph enables hierarchical agent architectures:\n\n| Pattern | Use Case | Description |\n|---------|----------|-------------|\n| **Supervisor** | Single task delegation | One agent routes to specialized sub-agents |\n| **Hierarchical** | Complex workflows | Multiple supervisor levels manage complexity |\n| **Collaborative** | Parallel processing | Agents share context and contribute to solution |\n\n## Advanced Patterns\n\n### Human-in-the-Loop\n\nIntegrating human feedback into agent execution:\n\n```python\ndef human_review_node(state: AgentState) -> AgentState:\n    user_input = interrupt(\"Awaiting human review...\")\n    return {\"feedback\": user_input}\n```\n\nThe `interrupt` function pauses execution and yields control to external systems (UIs, APIs) for human approval before resuming.\n\n### Memory Persistence\n\nLangGraph supports checkpointing for long-running conversations:\n\n```python\nfrom langgraph.checkpoint.sqlite import SqliteSaver\n\ncheckpointer = SqliteSaver.from_conn_string(\":memory:\")\ngraph = compileprompt | model | parser, checkpointer=checkpointer)\n```\n\nCheckpoints enable:\n- Conversation resumption after interruptions\n- Branching for exploration\n- Audit trails of agent decisions\n\n### Tool Integration\n\nTools are defined as functions and integrated into the graph:\n\n```python\nfrom langchain_core.tools import tool\n\n@tool\ndef search_codebase(query: str) -> str:\n    \"\"\"Search the codebase for relevant files.\"\"\"\n    # Implementation\n    return results\n\ntools = [search_codebase]\n```\n\n## API Reference\n\n### Compiling the Graph\n\n```python\nfrom langgraph.graph import StateGraph, END\n\nworkflow = StateGraph(AgentState)\nworkflow.add_node(\"agent\", agent_node)\nworkflow.add_node(\"tools\", tool_node)\n\nworkflow.set_entry_point(\"agent\")\nworkflow.add_conditional_edges(\n    \"agent\",\n    should_continue,\n    {\n        \"continue\": \"agent\",\n        \"end\": END,\n    }\n)\n\napp = workflow.compile()\n```\n\n### Key Parameters\n\n| Parameter | Type | Purpose |\n|-----------|------|---------|\n| `checkpointer` | BaseCheckpointSaver | Enables state persistence |\n| `interrupts` | list | Pause points for external input |\n| `debug` | bool | Enable verbose execution logging |\n\n## Best Practices\n\n### Error Handling\n\nImplement retry logic and fallbacks within nodes:\n\n```python\ndef robust_agent_node(state: AgentState) -> AgentState:\n    max_retries = 3\n    for attempt in range(max_retries):\n        try:\n            result = risky_operation(state)\n            return {\"result\": result, \"status\": \"success\"}\n        except Exception as e:\n            if attempt == max_retries - 1:\n                return {\"error\": str(e), \"status\": \"failed\"}\n            continue\n```\n\n### State Optimization\n\nMinimize state size to improve performance:\n\n- Use references (IDs) instead of full objects where possible\n- Implement state pruning at node boundaries\n- Separate ephemeral vs. persistent state concerns\n\n### Testing Strategies\n\n| Approach | Target | Method |\n|----------|--------|--------|\n| Unit tests | Individual nodes | Mock state input/output |\n| Integration tests | Full graph paths | Use deterministic checkpointer |\n| Property-based tests | State transitions | Verify invariants across runs |\n\n## Integration with s4b7-ai-skills\n\nThe LangGraph Agent Development skill follows the repository's skill template structure:\n\n- **Quick Start**: Minimal working example for agent initialization\n- **Workflows**: Step-by-step processes with checklists\n- **Advanced Features**: Referenced in companion files for specialized patterns\n\n资料来源：[skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n\n## Related Skills\n\n| Skill | Purpose |\n|-------|---------|\n| `shadow-refactor` | Code refactoring patterns for agent implementations |\n| `crystallize` | Extract reusable patterns from agent sessions |\n| `ai-sdk-core` | V5/V6 migration guidance for AI SDK integration |\n\n## Conclusion\n\nLangGraph Agent Development provides the architectural foundation for building sophisticated, stateful agent systems. By modeling agents as nodes in a graph with explicit state management and conditional routing, developers can create predictable, debuggable, and scalable agentic applications that handle complex multi-step workflows effectively.\n\n---\n\n<a id='ai-sdk-core'></a>\n\n## AI SDK Core - Vercel Integration\n\n### 相关页面\n\n相关主题：[LangGraph Agent Development](#langgraph-agent)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n- [skills/ai-sdk-core/references/v5-breaking-changes.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/v5-breaking-changes.md)\n- [skills/ai-sdk-core/references/top-errors.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/top-errors.md)\n- [skills/ai-sdk-core/references/providers-quickstart.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/providers-quickstart.md)\n- [skills/ai-sdk-core/references/links-to-official-docs.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/links-to-official-docs.md)\n</details>\n\n# AI SDK Core - Vercel Integration\n\n## Overview\n\nThe AI SDK Core skill provides a comprehensive toolkit for building backend AI applications using the Vercel AI SDK. It supports both stable v5 and v6 beta releases, offering capabilities for text generation, streaming, structured output, and agent-based workflows.\n\nThis skill targets developers implementing AI-powered backend routes, migrating between SDK versions, troubleshooting runtime errors, or integrating with latest AI models from OpenAI, Anthropic, and Google.\n\n**资料来源：** [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n\n## Skill Metadata\n\n| Property | Value |\n|----------|-------|\n| **Name** | AI SDK Core |\n| **Version** | 1.2.0 |\n| **Last Verified** | 2025-11-22 |\n| **Stable SDK Version** | 5.0.98 |\n| **Beta SDK Version** | 6.0.0-beta.107 |\n| **Production Tested** | Yes |\n| **License** | MIT |\n| **Dependencies** | ai-fi-manager |\n\n**资料来源：** [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n\n## Supported Capabilities\n\n### Core Functions\n\n| Function | Purpose |\n|----------|---------|\n| `generateText` | Non-streaming text generation |\n| `streamText` | Streaming text generation with real-time output |\n| `generateObject` | Structured output generation with Zod schema validation |\n| `streamObject` | Streaming structured object generation |\n\n### Advanced Features (v6 Beta)\n\n| Feature | Description |\n|---------|-------------|\n| **Agent Abstraction** | Built-in agent class with tool support |\n| **Tool Approval** | Human-in-the-loop approval workflow |\n| **Reranking Support** | Semantic search reranking capabilities |\n\n**资料来源：** [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n\n## Quick Start Workflow\n\n```mermaid\ngraph TD\n    A[Task Request] --> B{Identify Task Type}\n    B -->|New Route| C[Core Functions]\n    B -->|Agent/Tool Loop| D[v6 Agent Abstraction]\n    B -->|Migration| E[Breaking Change Checklist]\n    B -->|Error Fix| F[Error Cookbook]\n    C --> G[Install Packages]\n    D --> G\n    E --> H[Follow Migration Guide]\n    F --> I[Apply Recipe]\n    G --> J[Implement & Test]\n    H --> J\n    I --> J\n```\n\n### Installation\n\n```bash\nnpm install ai @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google zod\n\n# Beta lane when explicitly needed:\nnpm install ai@beta @ai-sdk/openai@beta @ai-sdk/react@beta\n```\n\n**资料来源：** [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n\n### Task Routing\n\n| Task | Starting Point |\n|------|----------------|\n| New backend AI route | Core functions: `generateText`, `streamText`, `generateObject`, `streamObject` |\n| Agent/tool loop | v6 Agent abstraction in `REFERENCE.md` |\n| v4→v5 migration | Breaking-change checklist in `REFERENCE.md` |\n| Cloudflare Worker startup | Lazy-import Workers fix in `REFERENCE.md` |\n| Runtime error | Error cookbook in `REFERENCE.md` |\n| Current model selection | Verify provider docs, then use provider examples in `REFERENCE.md` |\n\n**资料来源：** [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n\n## v4 to v5 Breaking Changes\n\nThe migration from v4 to v5 introduces several breaking changes that require code updates.\n\n**资料来源：** [skills/ai-sdk-core/references/v5-breaking-changes.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/v5-breaking-changes.md)\n\n### Message Types Renaming\n\n| v4 Type | v5 Type | Purpose |\n|---------|---------|---------|\n| `CoreMessage` | `ModelMessage` | Messages for the model |\n| `Message` | `UIMessage` | UI hooks |\n| `convertToCoreMessages` | `convertToModelMessages` | Conversion utility |\n\n**Before (v4):**\n```typescript\nimport { CoreMessage, convertToCoreMessages } from 'ai';\n\nconst messages: CoreMessage[] = [\n  { role: 'user', content: 'Hello' },\n];\n\nconst converted = convertToCoreMessages(uiMessages);\n```\n\n**After (v5):**\n```typescript\nimport { ModelMessage, convertToModelMessages } from 'ai';\n\nconst messages: ModelMessage[] = [\n  { role: 'user', content: 'Hello' },\n];\n\nconst converted = convertToModelMessages(uiMessages);\n```\n\n**资料来源：** [skills/ai-sdk-core/references/v5-breaking-changes.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/v5-breaking-changes.md)\n\n### Tool Error Handling\n\n| Aspect | v4 Behavior | v5 Behavior |\n|--------|-------------|-------------|\n| Error Type | `ToolExecutionError` | Regular `Error` |\n| Error Location | Thrown explicitly | Appears as content parts |\n| Execution Impact | Stops execution | Continues with error in stream |\n\n**Before (v4):**\n```typescript\nimport { ToolExecutionError } from 'ai';\n\nconst tools = {\n  risky: {\n    execute: async (args) => {\n      throw new ToolExecutionError({\n        message: 'API failed',\n        cause: originalError,\n      });\n    },\n  },\n};\n```\n\n**After (v5):**\n```typescript\nconst tools = {\n  risky: tool({\n    execute: async (input) => {\n      throw new Error('API failed');\n    },\n  }),\n};\n```\n\n**资料来源：** [skills/ai-sdk-core/references/v5-breaking-changes.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/v5-breaking-changes.md)\n\n## Error Solutions\n\nThe skill includes a cookbook with 12+ error solutions covering common runtime issues.\n\n| Error Category | Count | Coverage |\n|----------------|-------|----------|\n| `AI_APICallError` | 1+ | API communication failures |\n| `AI_NoObjectGeneratedError` | 1+ | Structured output failures |\n| Stream Text Silent Errors | 1+ | Stream consumption issues |\n| Cloudflare Workers Errors | 1+ | Worker-specific problems |\n\n**资料来源：** [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n\n### Common Decision Points\n\n| Scenario | Recommendation |\n|----------|-----------------|\n| Stable vs Beta | Prefer stable v5 unless v6 beta features explicitly requested |\n| Workers startup | Use lazy imports when startup budget matters |\n| Stream errors | Treat `streamText` silent failures as error-handling problem, not only provider problem |\n| Model IDs/Prices | Do not hard-code; verify first before use |\n\n**资料来源：** [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n\n## Provider Integration\n\n### Supported Providers\n\n| Provider | Package | Models |\n|----------|---------|--------|\n| OpenAI | `@ai-sdk/openai` | GPT-5, GPT-5.1 |\n| Anthropic | `@ai-sdk/anthropic` | Claude 4.x series |\n| Google | `@ai-sdk/google` | Gemini 2.5 |\n\n**资料来源：** [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n\n### Cloudflare Workers Special Handling\n\nCloudflare Workers have strict startup budgets. When implementing AI SDK in Workers environments:\n\n1. Use lazy imports for AI SDK packages\n2. Defer model initialization until first request\n3. Apply the Workers-specific fix from `REFERENCE.md`\n\n**资料来源：** [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n\n## Fallback Chain\n\nWhen primary references are unavailable or stale, use this fallback sequence:\n\n```mermaid\ngraph LR\n    A[Request] --> B{REFERENCE.md Available?}\n    B -->|Yes| C[Use Detailed Reference]\n    B -->|No| D{Web Search Available?}\n    D -->|Yes| E[Search Official Docs]\n    D -->|No| F{npm view Available?}\n    F -->|Yes| G[Check Latest Version]\n    F -->|No| H[Use Stable v5 Default]\n```\n\n| Priority | Source | Use Case |\n|----------|--------|----------|\n| 1 | `REFERENCE.md` detailed reference | Migrations, errors, model notes |\n| 2 | Web search / docs | Stale or missing version info |\n| 3 | `npm view ai versions` | Version uncertainty |\n| 4 | Stable v5 default | Last resort |\n\n**资料来源：** [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n\n## Artifact Routing\n\n| Artifact | Location | Purpose |\n|----------|----------|---------|\n| Code changes | Project files (inline) | Implementation output |\n| Detailed reference | `REFERENCE.md` (skill companion) | Migrations, errors, model notes |\n| Original backup | `data/skill-rd/active-split-backups/2026-05-02/ai-sdk-core.SKILL.original.md` | Pre-split archive |\n\n**资料来源：** [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n\n## Reference File Structure\n\n```\nskills/ai-sdk-core/\n├── SKILL.md                          # Main skill file\n├── REFERENCE.md                      # Detailed reference\n├── references/\n│   ├── v5-breaking-changes.md       # v4→v5 migration guide\n│   ├── top-errors.md                 # Error cookbook\n│   ├── providers-quickstart.md       # Provider setup\n│   └── links-to-official-docs.md     # External resources\n├── templates/\n│   ├── generate-text-basic.ts\n│   ├── stream-text-chat.ts\n│   └── generate-object-zod.ts\n└── data/\n    └── skill-rd/\n        └── active-split-backups/     # Archive versions\n```\n\n**资料来源：** [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n\n## External Resources\n\n| Resource | URL |\n|----------|-----|\n| Official Documentation | https://ai-sdk.dev/ |\n| GitHub Repository | https://github.com/vercel/ai |\n| GitHub Issues | https://github.com/vercel/ai/issues |\n| GitHub Discussions | https://github.com/vercel/ai/discussions |\n| Discord Community | https://discord.gg/vercel |\n| AI SDK 5.0 Release Blog | https://vercel.com/blog/ai-sdk-5 |\n| Zod Documentation | https://zod.dev/ |\n\n**资料来源：** [skills/ai-sdk-core/references/links-to-official-docs.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/links-to-official-docs.md)\n\n## Complementary Skills\n\n| Skill | Purpose |\n|-------|---------|\n| **ai-sdk-ui** | Frontend React hooks (`useChat`, `useCompletion`, `useObject`) |\n| **cloudflare-workers-ai** | Native Cloudflare Workers AI binding (single-provider) |\n\n**资料来源：** [skills/ai-sdk-core/references/links-to-official-docs.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/links-to-official-docs.md)\n\n## Keywords\n\nThe skill is triggered by these terms:\n\n- ai sdk core, vercel ai sdk, ai sdk v5, ai sdk v6 beta, ai sdk 6\n- agent abstraction, tool approval, reranking support\n- human in the loop, generateText, streamText\n- generateObject, streamObject, ai sdk node, ai sdk server\n- zod ai schema, ai schema validation, ai tool calling\n- ai agent class, openai sdk, anthropic sdk\n\n**资料来源：** [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n\n---\n\n<a id='agent-cryst'></a>\n\n## Agent Crystallization Protocol\n\n### 相关页面\n\n相关主题：[Crystallize - Pattern Extraction](#crystallize), [Write A Skill - Authoring Guide](#write-a-skill)\n\n<details>\n<summary>Relevant Source Files</summary>\n\nThe following source files were used to generate this documentation:\n\n- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n- [skills/agent-cryst/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/agent-cryst/SKILL.md)\n- [skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n- [skills/shadow-mind/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mind/SKILL.md)\n- [README.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/README.md)\n</details>\n\n# Agent Crystallization Protocol\n\nThe Agent Crystallization Protocol is a systematic methodology for transforming implicit knowledge, problem-solving patterns, and learned insights from agent sessions into explicit, reusable, and discoverable skills. It serves as the intentional counterpart to automated pattern detection (SP-006), enabling agents to capture knowledge that emerges from reasoning and understanding rather than mere tool usage observation.\n\n## Purpose and Scope\n\nThe crystallization protocol addresses a fundamental challenge in agentic systems: knowledge decay and inability to reuse past solutions. When an agent successfully solves a complex problem, that solution remains trapped in session memory unless explicitly captured. The crystallization protocol provides the workflow, standards, and tooling to extract these patterns into durable skills that future sessions can leverage.\n\n**Primary Objectives:**\n\n| Objective | Description |\n|-----------|-------------|\n| Knowledge Preservation | Convert session insights into persistent, reusable artifacts |\n| Pattern Formalization | Transform implicit heuristics into explicit, actionable workflows |\n| Skill Discoverability | Ensure crystallized knowledge is findable and loadable by agents |\n| Quality Assurance | Maintain skill standards through validation and documentation requirements |\n| Organizational Learning | Enable cross-session and cross-domain knowledge transfer |\n\n**Scope Boundaries:**\n\nThe protocol distinguishes between what should be crystallized and what should not:\n\n- **Crystallize:** Novel problem-solving approaches, reusable workflows, decision heuristics, gotchas discovered through reasoning, cross-domain patterns\n- **Do Not Crystallize:** Time-sensitive information (pricing, API versions), obvious operations derivable from codebase inspection, highly specific one-off solutions 资料来源：[skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n## Architecture Overview\n\nThe crystallization system operates as a closed loop between session execution and skill repository management:\n\n```mermaid\ngraph TD\n    A[Agent Session] -->|Completes Task| B{Should this recur?}\n    B -->|Yes| C[Review Session]\n    B -->|No| Z[Session Ends]\n    C --> D[Extract Pattern]\n    D --> E[Check Scope]\n    E --> F{Skill overlap found?}\n    F -->|Yes| G[Update Existing Skill]\n    F -->|No| H[Create New Skill]\n    G --> I[Log Crystallization Metadata]\n    H --> I\n    I --> J[Skill Repository]\n    J -->|Future Sessions| A\n```\n\n### Relationship to SP-006\n\nThe protocol intentionally complements SP-006 (Latent Skill Observer), which automatically detects patterns from tool call sequences:\n\n| Mechanism | Detection Method | Knowledge Type |\n|-----------|------------------|----------------|\n| SP-006 | Automated tool sequence analysis | Behavioral patterns from execution |\n| Crystallization Protocol | Intentional reasoning-based extraction | Conceptual patterns from understanding |\n\nBoth mechanisms feed into the same skill namespace, ensuring that automatically detected and intentionally crystallized knowledge coexist and reinforce each other. 资料来源：[skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n## Crystallization Workflow\n\nThe standard crystallization workflow proceeds through seven discrete phases:\n\n### Phase 1: Review Session\n\nBefore extracting any pattern, the agent must thoroughly understand what was accomplished:\n\n**Review Questions:**\n- What was the original task?\n- What problem was solved?\n- What was learned that wasn't known before?\n- What steps would be repeated identically in a similar future task?\n\nThis phase establishes the context necessary to determine whether crystallization is warranted and what form it should take. 资料来源：[skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n### Phase 2: Pattern Extraction\n\nThe core analytical phase where implicit knowledge becomes explicit. Extract four categories of information:\n\n**Key Steps:** The minimal sequence of actions that produces the desired result. Include only essential steps; omit accidental details from the specific session.\n\n**Heuristics:** The judgment calls required during execution. These are the \"rule of thumb\" decisions that determine success—where did the agent need to choose between approaches, and what guided that choice?\n\n**Gotchas:** What went wrong or nearly went wrong. Include assumptions that failed, edge cases that weren't anticipated, and common mistakes in the domain.\n\n**Decision Points:** Where the agent chose between competing approaches. Document both the choice made and the determining factors. 资料来源：[skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n### Phase 3: Exploratory Mode Expansion\n\nWhen the operator requests deeper crystallization or explicitly invokes `--exploratory-mode`, the protocol expands one \"ring\" outward from the immediate fix:\n\n```mermaid\ngraph LR\n    A[Exact Fix] --> B[Adjacent Surface 1]\n    A --> C[Adjacent Surface 2]\n    A --> D[Adjacent Surface 3]\n    B --> E{Same Stale Assumption?}\n    C --> E\n    D --> E\n    E -->|Yes| F[Capture Broader Pattern]\n    E -->|No| G[Leave Untouched]\n```\n\n**Exploratory Sweep Process:**\n1. Identify the exact element that was fixed\n2. Check the nearest adjacent surfaces that could carry the same stale assumption\n3. Evaluate whether the extracted pattern applies broadly or is specific to one surface\n4. Capture the broader reusable rule if the pattern holds across surfaces\n5. Explicitly note which adjacent surfaces were checked and intentionally left untouched 资料来源：[skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n### Phase 4: Scope Determination\n\nBefore creating or updating skills, determine the appropriate scope:\n\n| Scope | Location | Use Case |\n|-------|----------|----------|\n| General patterns | `~/.agents/skills/<skill-name>/SKILL.md` | Cross-domain, reusable anywhere |\n| Enterprise-specific | `~/.agents/skills/<enterprise>/` | Domain-scoped, team-specific |\n\nScope determination prevents the creation of skills that are either too narrow (duplicating existing capabilities) or too broad (mixing concerns that should be separate). 资料来源：[skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n### Phase 5: Deduplication Search\n\nBefore creating a new skill, search for existing skills that may overlap:\n\n**Search Targets:**\n- Skills with similar triggers or descriptions\n- Skills in adjacent domains that might subsume the new pattern\n- Deprecated skills that might redirect to canonical locations\n\n**Decision Matrix:**\n\n| Scenario | Action |\n|----------|--------|\n| Exact overlap found | Extend existing skill with new section |\n| Partial overlap found | Add to existing skill, avoid duplication |\n| Related but distinct | Create as separate skill, consider cross-reference |\n| No overlap found | Proceed with new skill creation |\n\nIf a related skill exists, add the new pattern as a new section or extend the existing workflow while preserving the skill's existing structure. 资料来源：[skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n### Phase 6: Skill Creation or Update\n\n#### Creating a New Skill\n\nFollow the standardized skill structure:\n\n```\n~/.agents/skills/<skill-name>/\n├── SKILL.md           # Primary skill definition\n├── REFERENCE.md       # Detailed reference (optional)\n└── scripts/           # Utility scripts (if needed)\n    └── helper.js\n```\n\n#### Updating an Existing Skill\n\nWhen extending an existing skill:\n1. Add new sections without modifying existing content structure\n2. Extend workflows only when the new pattern logically belongs\n3. Preserve all existing gotchas and decision points\n4. Update the \"Crystallized From\" metadata\n\n#### SKILL.md Template Structure\n\n```markdown\n---\nname: skill-name\ndescription: Brief description of capability. Use when [specific triggers].\n---\n\n# Skill Name\n\n## Quick start\n\n[Minimal working example]\n\n## Workflows\n\n[Step-by-step processes with checklists for complex tasks]\n\n## Advanced features\n\n[Link to separate files: See [REFERENCE.md](REFERENCE.md)]\n```\n\nThe `description` field is critical—it is the only information the agent sees when deciding which skill to load. It must include:\n- Maximum 1024 characters\n- Third-person perspective\n- First sentence: what the skill does\n- Second sentence: specific trigger conditions 资料来源：[skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n\n### Phase 7: Crystallization Logging\n\nRecord metadata at the bottom of the skill under `## Crystallized From`:\n\n```markdown\n## Crystallized From\n- Session: [date/context]\n- Original task: [what was being solved]\n- Pattern extracted: [what was captured]\n- Exploration mode: [what surfaces were checked]\n```\n\n**Optional:** Append to `docs/plans/crystallization-log.md` for historical tracking of all crystallizations. 资料来源：[skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n## Crystallization Modes\n\nThe protocol supports multiple modes to accommodate different urgency levels and depth requirements:\n\n| Mode | Output | Trigger Conditions |\n|------|--------|-------------------|\n| `default` | Full crystallization: review → extract → scope → deduplicate → create/update | `crystallize`, `capture this as a skill` |\n| `quick` | Fast capture to minimal skill stub; full refinement later | `quick crystallize`, mid-task pattern discovery |\n| `exploratory` | Expand one ring outward; check adjacent surfaces for same pattern | `--exploratory-mode`, `more crystallization` |\n| `drag-response` | Immediate crystallization from operator frustration | `this took too long`, `why aren't you using...` |\n| `correction` | Immediate update from operator correction | Operator corrects an identity/path/boundary |\n| `audit` | Check what should have been crystallized but wasn't | `what patterns did we miss` |\n\nThe mode determines the depth of analysis and the scope of expansion. Default mode provides thorough coverage; exploratory mode extends to adjacent surfaces; drag-response and correction modes prioritize speed for immediate pain points. 资料来源：[skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n## Artifact Routing\n\nAll crystallization outputs are routed to specific destinations based on their type:\n\n| Artifact Type | Destination | Purpose |\n|---------------|-------------|---------|\n| New skill | `~/.agents/skills/<slug>/SKILL.md` | Reusable capability |\n| Updated skill | Same path as existing skill | Extended capability |\n| Crystallization log | `docs/plans/crystallization-log.md` | Historical tracking (optional) |\n| Enterprise-specific skill | Appropriate `~/.agents/skills/<enterprise>/` subdirectory | Domain-scoped capability |\n\nSkill companions (detailed references, scripts) are co-located with their parent SKILL.md file. 资料来源：[skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n## Fallback Chain\n\nWhen primary resources are unavailable, the protocol follows a defined fallback chain:\n\n```\n1. Primary: Full workflow execution\n2. Fallback: Scan alternate skill paths\n3. Fallback: Skip unavailable services (Caresoft API, mesh nodes)\n4. Fallback: Report degraded state, continue with available data\n5. Last Resort: Minimal scan of current working directory only\n```\n\n| Failure | Recovery Action |\n|---------|----------------|\n| Primary skill directory not found | Check alternate paths; report; scan what's available |\n| ShadowArchive unmounted | Scan local paths only; note archive scan skipped |\n| Mesh unreachable | Skip mesh health checks; note offline nodes; continue |\n| Caresoft API unavailable | Report; skip engineering intelligence mode |\n| Skills directory empty | Report; likely path issue; suggest checking `~/.agents/skills/` |\n\nThe fallback chain ensures that crystallization can proceed at reduced fidelity rather than failing entirely when infrastructure components are unavailable. 资料来源：[skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n## Integration with Session Memory\n\nCrystallization does not operate in isolation—it integrates with broader session memory practices. After every session that produces decisions or discoveries:\n\n```mermaid\ngraph TD\n    A[Session Complete] --> B[Write Session Anchor]\n    B --> C[Append to ESP Context]\n    C --> D{Is this a reusable pattern?}\n    D -->|Yes| E[Crystallize to Skill]\n    D -->|No| F{Program-specific?}\n    F -->|Yes| G[Write to Session Log JSONL]\n    F -->|No| H[Discard or Archive]\n```\n\n**Session Anchor Storage:**\n- Write anchor to `ShadowArchive/80-reports/`\n- Append key decisions to `.shadow-kernel/esp-context.md` under topic heading\n- If pattern discovered → crystallize to skill\n- If program-specific → write to `<program>/90_Astemo_Config/session-log.jsonl` 资料来源：[skills/shadow-mind/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mind/SKILL.md)\n\n## Validation and Quality Standards\n\nCrystallized skills must meet minimum quality standards before being committed:\n\n### Review Checklist\n\n| Requirement | Standard |\n|-------------|----------|\n| Description | Includes trigger phrases (\"Use when...\") |\n| Length | SKILL.md under 100 lines |\n| Currency | No time-sensitive information without freshness notes |\n| Terminology | Consistent throughout the skill |\n| Examples | Concrete, working examples included |\n| References | Links to one level deep (e.g., REFERENCE.md, not REFERENCE.md#section |\n\n### Skill Validation\n\nWhen using skill validation tooling:\n- Ensure YAML frontmatter is properly formatted\n- Verify description character count under 1024\n- Confirm trigger phrases are present and specific\n- Check that workflows include actionable checklists 资料来源：[skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n\n## Contract and Boundaries\n\nThe crystallization protocol operates under explicit contracts that define acceptable behavior:\n\n| Contract Element | Requirement |\n|-----------------|--------------|\n| Context Scope | Context is session-scoped; do not persist without operator request |\n| Zone Boundaries | Respect zone boundaries; enterprise context does not leak into personal zone |\n| Recall Confidence | Always label recall confidence (Confirmed/Likely/Inferred/Unknown) |\n| Inference Presentation | Never present inferred recall as confirmed |\n| Memory Persistence | Memory writes are append-only, never destructive |\n| Skill Preservation | Do not delete skills during exploratory surgery; redirect first |\n| Omnibus Prevention | Do not create giant omnibus skills; prefer focused subskills with canonical router |\n| Externalization | All surgery reports go to ShadowArchive; no inline deletion |\n\nThese contracts ensure that crystallization enhances rather than compromises system integrity and operator trust. 资料来源：[skills/shadow-mind/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mind/SKILL.md)\n\n## Quick Reference\n\n### Triggering Crystallization\n\n```bash\n# Full crystallization\ncrystallize\n\n# Quick capture\nquick crystallize\n\n# Deep exploration\ncrystallize --exploratory-mode\n\n# Check for missed patterns\nwhat patterns did we miss\n```\n\n### Skill Discovery\n\n```bash\n# List available skills\nls ~/.agents/skills/\n\n# Search for specific capability\ngrep -r \"trigger phrase\" ~/.agents/skills/\n\n# Validate skill structure\nskill_validate <skill-path>\n```\n\n### Common Crystallization Patterns\n\n| Pattern Type | Best Practice |\n|--------------|---------------|\n| Novel workflow | Create dedicated skill with full template |\n| Extension to existing | Add new section, preserve existing structure |\n| Domain-specific | Create in appropriate enterprise subdirectory |\n| Cross-domain | Create in root, add cross-references |\n| Time-sensitive | Include freshness date and deprecation notice |\n\n## Related Documentation\n\n| Document | Purpose |\n|----------|---------|\n| [Agent Building Skills](../README.md#agent-building) | Overview of agent construction capabilities |\n| [write-a-skill](write-a-skill/SKILL.md) | Detailed skill authoring guide |\n| [skill-surgery-rd](skill-surgery-rd/SKILL.md) | Skill audit, repair, and gap analysis |\n| [shadow-mind](shadow-mind/SKILL.md) | Session memory and context management |\n\n---\n\n<a id='write-a-skill'></a>\n\n## Write A Skill - Authoring Guide\n\n### 相关页面\n\n相关主题：[Crystallize - Pattern Extraction](#crystallize), [Skill Surgery R&D](#skill-surgery-rd), [Skill Structure & Anatomy](#skill-structure)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n- [skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n- [skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)\n- [skills/codex-context/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-context/SKILL.md)\n</details>\n\n# Write A Skill - Authoring Guide\n\n## Overview\n\nThe **Write A Skill** authoring guide provides a standardized template and methodology for creating reusable agent capabilities within the skills ecosystem. Skills are self-contained units of functionality that agents can load and invoke based on context, enabling modular and maintainable agent behavior. 资料来源：[skills/write-a-skill/SKILL.md:1-15]()\n\nThis guide defines the canonical structure for skill development, including metadata requirements, workflow documentation patterns, and organizational best practices. The authoring framework ensures consistency across all skills while maintaining flexibility for diverse use cases.\n\n## Skill Anatomy\n\n### Core Components\n\nEvery skill follows a standardized directory structure to ensure predictability and discoverability:\n\n```\nskill-name/\n├── SKILL.md          # Primary documentation and entry point\n├── REFERENCE.md      # Advanced usage (optional)\n├── docs/             # Additional documentation (if needed)\n└── scripts/          # Utility scripts (if needed)\n    └── helper.js\n```\n\n资料来源：[skills/write-a-skill/SKILL.md:1-7]()\n\n### SKILL.md Template\n\nThe `SKILL.md` file serves as the primary interface for skill discovery and usage. It must follow this structure:\n\n```markdown\n---\nname: skill-name\ndescription: Brief description of capability. Use when [specific triggers].\n---\n\n# Skill Name\n\n## Quick start\n[Minimal working example]\n\n## Workflows\n[Step-by-step processes with checklists for complex tasks]\n\n## Advanced features\n[Link to separate files: See [REFERENCE.md](REFERENCE.md)]\n```\n\n资料来源：[skills/write-a-skill/SKILL.md:9-23]()\n\n## Metadata Requirements\n\n### Frontmatter Schema\n\nThe YAML frontmatter is **critical** for skill discovery. The agent system reads these fields to determine when to activate a skill.\n\n| Field | Type | Constraints | Purpose |\n|-------|------|-------------|---------|\n| `name` | string | lowercase, hyphenated | Unique identifier for the skill |\n| `description` | string | max 1024 chars, third person | Decision surface for skill selection |\n\n### Description Writing Guidelines\n\nThe description is **the only thing the agent sees** when deciding which skill to load. It appears in the system prompt alongside all other installed skills.\n\n**Required Format:**\n\n1. **First sentence**: What the capability provides\n2. **Second sentence**: Trigger conditions beginning with \"Use when...\"\n\n**Good Example:**\n```\nExtract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.\n```\n\n**Bad Examples:**\n```\nHelps with documents.\nPDF helper tool.\n```\n\n资料来源：[skills/write-a-skill/SKILL.md:33-48]()\n\nThe description must enable the agent to make an informed routing decision without additional context. Vague descriptions provide no discriminative value.\n\n## Content Organization\n\n### When to Add Scripts\n\nScripts should be introduced in specific scenarios:\n\n| Scenario | Rationale |\n|----------|-----------|\n| Operation is deterministic | Validation, formatting, or transformation logic that produces consistent results |\n| Same code would be generated repeatedly | DRY principle application; avoid token waste on regeneration |\n| Errors need explicit handling | Centralized error management with clear recovery paths |\n\nScripts save tokens and improve reliability compared to generated code. 资料来源：[skills/write-a-skill/SKILL.md:62-68]()\n\n### When to Split Files\n\nSplit into separate files when any of the following conditions are met:\n\n| Condition | Threshold | Rationale |\n|-----------|-----------|-----------|\n| SKILL.md exceeds | 100 lines | Maintain single-screen readability |\n| Content has distinct domains | N/A | Finance vs. sales schemas require separate handling |\n| Advanced features are rarely needed | N/A | Avoid cognitive overload for common use cases |\n\n资料来源：[skills/write-a-skill/SKILL.md:70-77]()\n\n## Workflow Documentation\n\n### Checklist Patterns\n\nFor complex tasks, use step-by-step checklists:\n\n```markdown\n## Workflows\n\n1. [ ] Prepare environment\n2. [ ] Validate inputs\n3. [ ] Execute operation\n4. [ ] Verify output\n5. [ ] Report results\n```\n\n### Mode Tables\n\nDocument different operational modes using tables:\n\n| Mode | Output | When |\n|------|--------|------|\n| `default` | Full operation | Normal use |\n| `quick` | Minimal output | Time-constrained scenarios |\n| `verbose` | Detailed diagnostics | Debugging |\n\n## Skill Lifecycle\n\n### Crystallization Workflow\n\nNew skills often emerge from successful problem-solving sessions. The crystallization workflow formalizes this knowledge capture:\n\n```mermaid\ngraph TD\n    A[T] --> B{Should this recur?}\n    B -->|yes| C[Review session]\n    B -->|no| D[Done]\n    C --> E[Extract pattern]\n    E --> F[Check scope]\n    F --> G{Search existing skills}\n    G -->|overlap found| H[Update existing]\n    G -->|no overlap| I[Create new skill]\n    H --> J[Log crystallization]\n    I --> J\n```\n\n资料来源：[skills/crystallize/SKILL.md:45-60]()\n\n### Crystallization Modes\n\n| Mode | Output | Trigger Phrases |\n|------|--------|-----------------|\n| `default` | Full crystallization | `crystallize`, `capture this as a skill` |\n| `quick` | Minimal skill stub | `quick crystallize`, mid-task pattern discovery |\n| `exploratory` | Expanded pattern capture | `--exploratory-mode`, `more crystallization` |\n| `drag-response` | Immediate capture | `this took too long`, `why aren't you using...` |\n| `correction` | Immediate update | Operator correction |\n| `audit` | Gap analysis | `what patterns did we miss` |\n\n资料来源：[skills/crystallize/SKILL.md:63-72]()\n\n## Review Checklist\n\nBefore finalizing a skill, verify the following:\n\n| Item | Requirement | Validation |\n|------|-------------|------------|\n| Description | Includes triggers (\"Use when...\") | Check second sentence format |\n| Length | SKILL.md under 100 lines | Line count |\n| Timelessness | No time-sensitive info | Scan for dates, deadlines |\n| Terminology | Consistent naming | Cross-reference glossary |\n| Examples | Concrete use cases included | At least one working example |\n| Depth | References one level deep | Check cross-links |\n\n资料来源：[skills/write-a-skill/SKILL.md:79-87]()\n\n## Artifact Routing\n\nSkills should specify where outputs and artifacts are stored:\n\n| Artifact | Path Pattern | Purpose |\n|----------|--------------|---------|\n| New skill | `~/.agents/skills/<slug>/SKILL.md` | Reusable capability |\n| Updated skill | Same path as existing | Extended capability |\n| Crystallization log | `docs/plans/crystallization-log.md` | History tracking |\n\n资料来源：[skills/crystallize/SKILL.md:76-81]()\n\n## Integration with Agent Context\n\n### Relationship to SP-006\n\nThe `crystallize` skill complements SP-006 (latent skill observer) by adding **intentional** crystallization from reasoning. While SP-006 automatically detects patterns from tool call sequences, this skill captures patterns from understanding the problem domain. Both mechanisms feed the same skill namespace. 资料来源：[skills/crystallize/SKILL.md:84-88]()\n\n### Context Loading\n\nSkills should integrate with the broader agent context system:\n\n```mermaid\ngraph LR\n    A[Agent Request] --> B[Skill Loader]\n    B --> C{Skill Description Match?}\n    C -->|yes| D[Load SKILL.md]\n    C -->|no| E[Continue Search]\n    D --> F[Execute Workflow]\n```\n\nSkills are discovered through description matching, not file naming. The agent evaluates the `description` field against the current request context.\n\n## Best Practices\n\n### Naming Conventions\n\n| Element | Convention | Example |\n|---------|------------|---------|\n| Skill directory | kebab-case | `pdf-extract` |\n| Skill name | lowercase, hyphenated | `pdf-extract` |\n| Script files | camelCase or kebab-case | `helper.js`, `validate-input.js` |\n| Reference docs | Title Case | `REFERENCE.md` |\n\n### Error Handling\n\n| Error Type | Recommended Approach |\n|------------|---------------------|\n| Validation failure | Provide clear error message with correction guidance |\n| Missing dependencies | Document prerequisites in SKILL.md |\n| Runtime errors | Include troubleshooting section |\n\n### Documentation Depth\n\nMaintain appropriate abstraction levels:\n\n- **SKILL.md**: Quick reference, common workflows\n- **REFERENCE.md**: Edge cases, API details, advanced configuration\n- **scripts/**: Implementations, not documentation\n\n## Related Skills\n\n| Skill | Relationship | Purpose |\n|-------|--------------|---------|\n| `crystallize` | Companion | Pattern extraction from sessions |\n| `skill-surgery-rd` | Operational | Skill maintenance and auditing |\n| `shadow-refactor` | Pattern source | Refactoring patterns become skills |\n\n资料来源：[skills/skill-surgery-rd/SKILL.md:1-10]()\n\n## Contract\n\nWhen authoring skills, adhere to these principles:\n\n1. **Do not invent behavior** not supported by the source files\n2. **Cite all claims** using the format `资料来源：[path/to/file.ext:line-line]()`\n3. **Preserve operator boundaries** when consolidating domain-specific skills\n4. **Externalize reports** to appropriate artifact paths\n\n资料来源：[skills/skill-surgery-rd/SKILL.md:110-118]()\n\n---\n\n<a id='crystallize'></a>\n\n## Crystallize - Pattern Extraction\n\n### 相关页面\n\n相关主题：[Agent Crystallization Protocol](#agent-cryst), [Write A Skill - Authoring Guide](#write-a-skill), [Skill Surgery R&D](#skill-surgery-rd)\n\n<details>\n<summary>Related Source Files</summary>\n\nThe following source files were used to generate this documentation:\n\n- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n</details>\n\n# Crystallize - Pattern Extraction\n\n## Overview\n\nCrystallize is a systematic skill for extracting reusable patterns from completed task sessions and capturing them as persistent, reusable skills. It transforms tacit knowledge gained during problem-solving into explicit, structured documentation that can be leveraged in future tasks.\n\nThe Crystallize skill serves as a complementary mechanism to SP-006 (latent skill observer), which automatically detects patterns from tool call sequences. While SP-006 observes tool usage, Crystallize adds **intentional** extraction from reasoning—patterns that emerge from understanding the problem domain, not just from observing execution traces.\n\n## Core Purpose\n\nThe primary objectives of Crystallize are:\n\n| Objective | Description |\n|-----------|-------------|\n| **Knowledge Capture** | Transform implicit problem-solving knowledge into explicit documentation |\n| **Reuse Enablement** | Create persistent skills that can be triggered in similar future contexts |\n| **Pattern Standardization** | Establish consistent structures for skill documentation |\n| **Continuous Improvement** | Build a growing library of battle-tested patterns |\n\n## Workflow\n\nThe Crystallize process follows a structured decision tree that determines whether a pattern warrants extraction and how it should be documented.\n\n```mermaid\ngraph TD\n    A[Task Complete] --> B{Should this recur?}\n    B -->|Yes| C[Review Session]\n    B -->|No| Z[Done]\n    C --> D[Extract Pattern]\n    D --> E[Check Scope]\n    E --> F[Search Existing Skills]\n    F -->|Overlap Found| G[Update Existing]\n    F -->|No Overlap| H[Create New Skill]\n    G --> I[Log Crystallization]\n    H --> I\n    I --> Z\n```\n\n### Phase 1: Review\n\nThe review phase establishes context by answering fundamental questions about the completed task:\n\n- **What was the task?** — Define the original objective\n- **What problem was solved?** — Identify the core challenge\n- **What did I learn?** — Extract the key insight or technique\n- **What steps would I repeat next time?** — Determine the reusable sequence\n\n资料来源：[skills/crystallize/SKILL.md:1-20]()\n\n### Phase 2: Pattern Extraction\n\nThis phase identifies the reusable elements from the completed session:\n\n| Element | Description |\n|---------|-------------|\n| **Key Steps** | Minimal sequence that produces the result |\n| **Heuristics** | Judgment calls, rules of thumb that emerged |\n| **Gotchas** | What went wrong or nearly went wrong; assumptions that failed |\n| **Decision Points** | Where approaches were chosen; what determined the choice |\n\n### Phase 3: Scope Check\n\nDetermine whether the pattern is:\n\n- **General** — Applicable across multiple domains or tasks\n- **Domain-Specific** — Limited to a particular technology, framework, or context\n\n### Phase 4: Deduplication\n\nSearch existing skills to prevent overlap:\n\n1. Check for similar trigger phrases in other skill descriptions\n2. Evaluate whether the pattern extends or supersedes existing skills\n3. Make the create-vs-update decision\n\n### Phase 5: Create or Update Skill\n\n#### Creating a New Skill\n\nPlace skills in the appropriate location based on scope:\n\n| Scope | Location |\n|-------|----------|\n| General patterns | `~/.agents/skills/<skill-name>/SKILL.md` |\n| Enterprise-specific | `~/.agents/skills/<enterprise-subdirectory>/` |\n\n#### Updating an Existing Skill\n\nWhen overlap is found, add the new pattern as a new section or extend the existing workflow. Preserve the skill's existing structure while integrating the new information.\n\n### Phase 6: Log the Crystallization\n\nRecord metadata at the bottom of the skill under `## Crystallized From`:\n\n```markdown\n## Crystallized From\n- Session: [date/context]\n- Original task: [what was being solved]\n- Pattern extracted: [what pattern was extracted]\n- Exploratory mode notes: [adjacent surfaces checked and left untouched]\n```\n\n## Crystallization Modes\n\nThe Crystallize skill supports multiple operational modes to handle different crystallization scenarios:\n\n| Mode | Output | Trigger Phrases |\n|------|--------|-----------------|\n| `default` | Full crystallization: review → extract → scope → deduplicate → create/update | `crystallize`, `capture this as a skill` |\n| `quick` | Fast capture to a minimal skill stub (full refinement later) | `quick crystallize`, `mid-task pattern discovery` |\n| `exploratory` | Expand one ring outward; check adjacent surfaces for same pattern | `--exploratory-mode`, `more crystallization` |\n| `drag-response` | Immediate crystallization triggered by operator frustration | `this took too long`, `why aren't you using...` |\n| `correction` | Immediate update from operator correction | Operator corrects an identity/path/boundary |\n| `audit` | Check what should have been crystallized but wasn't | `what patterns did we miss` |\n\n### Exploratory-Mode Expansion\n\nWhen the operator requests exploratory mode, do not stop at the first local fix. Expand one ring outward using this sweep:\n\n1. Start from the exact thing that was fixed\n2. Check the nearest adjacent surfaces that could carry the same stale assumption\n3. Capture the broader reusable rule\n\n## Artifact Routing\n\nAll crystallization artifacts are routed to specific locations based on their type and purpose:\n\n| Artifact Type | Path | Purpose |\n|---------------|------|---------|\n| New skill | `~/.agents/skills/<slug>/SKILL.md` | Reusable capability |\n| Updated skill | Same path as existing skill | Extended capability |\n| Crystallization log | `docs/plans/crystallization-log.md` | History of all crystallizations (optional) |\n| Enterprise-specific skill | Appropriate `~/.agents/skills/` subdirectory | Domain-scoped capability |\n\n## SKILL.md Template\n\nWhen creating a new crystallized skill, use this structure:\n\n```markdown\n# Skill Name\n\nOne-line description. Use when [trigger phrases].\n\n## When to Use\n- [trigger 1]\n- [trigger 2]\n- [trigger 3]\n\n## Workflow\n1. [Step 1]\n2. [Step 2]\n3. [Step 3]\n\n## Key Decisions\n- [Decision point 1]: [default choice + why]\n- [Decision point 2]: [default choice + why]\n\n## Gotchas\n- [Common mistake 1]\n- [Common mistake 2]\n\n## Crystallized From\n- Session: [date/context]\n- Original task: [what was being solved]\n```\n\n## Fallback Chain\n\nWhen primary methods are unavailable, Crystallize follows a fallback chain:\n\n1. **Primary:** Full workflow — review → extract → scope → deduplicate → create/update\n2. **Quick mode unavailable:** Capture to minimal stub\n3. **Existing skills check fails:** Create new skill without deduplication check\n4. **Logging unavailable:** Skip optional crystallization log entry\n\n## Relationship with SP-006\n\n| Aspect | SP-006 | Crystallize |\n|--------|--------|-------------|\n| Detection Method | Automatic tool call sequence analysis | Intentional reasoning-based extraction |\n| Input | Tool usage patterns | Session review and understanding |\n| Trigger | Passive observation | Active decision to crystallize |\n| Output | Latent skill candidates | Explicit, documented skills |\n\nBoth mechanisms feed the same skill namespace, meaning patterns captured via Crystallize become available alongside automatically detected patterns from SP-006.\n\n## Best Practices\n\n1. **Capture decision rationale** — Not just what was done, but why it was chosen over alternatives\n2. **Include failure modes** — Document what assumptions failed and what went wrong\n3. **Be specific with triggers** — Include exact phrases that should activate the skill\n4. **Maintain minimal examples** — Keep the workflow concise; detailed reference material can be separate files\n5. **Log the crystallization context** — Future maintainers need to understand the original problem\n\n---\n\n<a id='skill-surgery-rd'></a>\n\n## Skill Surgery R&D\n\n### 相关页面\n\n相关主题：[Crystallize - Pattern Extraction](#crystallize), [Write A Skill - Authoring Guide](#write-a-skill)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n- [skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)\n- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n- [skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n- [skills/shadow-engg/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-engg/SKILL.md)\n</details>\n\n# Skill Surgery R&D\n\n## Overview\n\nSkill Surgery R&D is a specialized operational capability within the shadow-verse ecosystem designed to audit, maintain, and optimize the skill garden. It provides structured workflows for analyzing skill inventory, detecting overlaps, identifying gaps, and performing surgical interventions on skill files.\n\n**Purpose**: The skill serves as a meta-level operations layer that ensures the skill ecosystem remains healthy, non-redundant, and properly aligned with user intents.\n\n**Scope**: Skill Surgery R&D operates across the entire skill inventory, examining both structural integrity and semantic coverage of installed skills.\n\n资料来源：[skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n\n## Architecture\n\n### Skill Surgery R&D Structure\n\n```\nskill-surgery-rd/\n├── SKILL.md                              (main skill definition)\n├── scripts/\n│   ├── audit-skills.mjs                  (inventory scanner)\n│   └── redirect-deprecated-skill.mjs     (redirect migration)\n├── data/skill-rd/\n│   ├── skill-inventory.json              (machine-readable catalog)\n│   └── semantic-duplicate-clusters.json   (overlap analysis)\n└── ShadowArchive/80-reports/\n    └── skill-rd-YYYY-MM-DD.md            (surgery reports)\n```\n\n### Skill Classification Taxonomy\n\nThe system classifies skills into the following categories for surgical planning:\n\n| Category | Definition | Treatment |\n|----------|------------|-----------|\n| `trigger-deprecated` | Deprecated skill that still receives lookups | Redirect to canonical skill |\n| `trigger-repair` | Skill with weak \"Use when...\" triggers | Rewrite frontmatter description |\n| `overlap` | Multiple skills cover same user intent | Merge candidates |\n| `stale-lane` | Legacy skill with active-looking instructions but no active trigger | Deprecate gracefully |\n| `runtime-gap` | Workflow described but lacks deterministic scripts | Create helper scripts |\n\n资料来源：[skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n\n## Operational Modes\n\nSkill Surgery R&D supports multiple operational modes for different use cases:\n\n| Mode | Output | When to Use |\n|------|--------|-------------|\n| `default` | Full audit → classify → propose surgeries | `skill surgery`, `audit skills` |\n| `inventory` | Scan and list all skills with metadata | `inventory skills`, `list skills` |\n| `gaps` | Gap classification only (no surgery) | `skill gaps`, `what's missing` |\n| `overlaps` | Overlap/duplicate detection | `duplicate skills`, `overlaps` |\n| `redirect <old> <new>` | Redirect deprecated skill to replacement | Specific redirect request |\n| `merge <a> <b>` | Merge two skills into canonical form | Specific merge request |\n| `trim <skill>` | Move detail from SKILL.md to REFERENCE.md | Specific trim request |\n| `research <topic>` | Research new skill candidates | `research skill for X` |\n\n资料来源：[skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n\n## Surgical Operations\n\n### Surgery Decision Workflow\n\n```mermaid\ngraph TD\n    A[Audit Skill Garden] --> B{Classification}\n    B -->|trigger-deprecated| C[Redirect Operation]\n    B -->|trigger-repair| D[Rewrite Frontmatter]\n    B -->|overlap| E[Merge Operation]\n    B -->|stale-lane| F[Trim + Deprecate]\n    B -->|runtime-gap| G[Create Scripts]\n    C --> H[Validate Changes]\n    D --> H\n    E --> H\n    F --> H\n    G --> H\n    H --> I[Report Outcomes]\n```\n\n### Surgery Types\n\n#### 1. Redirect\n\nRedirects a deprecated skill to its canonical replacement while preserving migration guidance.\n\n```bash\n# Redirect a deprecated skill\nnode /Users/sdluffy/.agents/skills/skill-surgery-rd/scripts/redirect-deprecated-skill.mjs \\\n  --mapping=data/skill-rd/map.json\n```\n\n**Validation criteria**:\n- Confirm target canonical skill exists\n- Preserve migration notes in redirect\n- Verify no active triggers point to deprecated path\n\n#### 2. Trigger Repair\n\nRewrites the frontmatter description with concrete \"Use when...\" triggers.\n\n**Before**:\n```yaml\n---\nname: document-skill\ndescription: Helps with documents.\n---\n```\n\n**After**:\n```yaml\n---\nname: document-skill\ndescription: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.\n---\n```\n\n#### 3. Trim\n\nMoves rare detail from `SKILL.md` to `REFERENCE.md` when the main file exceeds 100 lines.\n\n**Trigger conditions**:\n- SKILL.md exceeds 100 lines\n- Content has distinct domains\n- Advanced features are rarely needed\n\n#### 4. Merge\n\nConsolidates overlapping skills after confirming one canonical owner and preserving useful gotchas.\n\n**Merge criteria**:\n- One canonical owner identified\n- Non-overlapping useful gotchas exist\n- Semantic duplication confirmed\n\n#### 5. Create\n\nCreates new skills only when no existing skill owns the lane.\n\n**Research requirements**:\n- Verify current docs or product state first\n- Store source links and date in companion `RESEARCH.md`\n- Never crystallize stale version numbers without freshness note\n\n资料来源：[skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n\n## Bundled Scripts\n\n### Audit Skills Script\n\nGenerates JSON reports for the skill inventory:\n\n```bash\nnode /Users/sdluffy/.agents/skills/skill-surgery-rd/scripts/audit-skills.mjs \\\n  --out=data/skill-rd\n```\n\n**Outputs**:\n| Artifact | Path | Purpose |\n|----------|------|---------|\n| Skill inventory | `data/skill-rd/skill-inventory.json` | Machine-readable catalog |\n| Duplicate clusters | `data/skill-rd/semantic-duplicate-clusters.json` | Overlap analysis |\n\n### Redirect Deprecated Skill Script\n\nDry-run or apply reversible redirects from a mapping file:\n\n```bash\n# Dry run\nnode /Users/sdluffy/.agents/skills/skill-surgery-rd/scripts/redirect-deprecated-skill.mjs \\\n  --mapping=data/skill-rd/map.json --dry-run\n\n# Apply\nnode /Users/sdluffy/.agents/skills/skill-surgery-rd/scripts/redirect-deprecated-skill.mjs \\\n  --mapping=data/skill-rd/map.json\n```\n\n资料来源：[skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n\n## Artifact Routing\n\nAll surgery artifacts follow a standardized routing structure:\n\n| Artifact | Path | Purpose |\n|----------|------|---------|\n| Skill inventory | `data/skill-rd/skill-inventory.json` | Machine-readable catalog |\n| Duplicate clusters | `data/skill-rd/semantic-duplicate-clusters.json` | Overlap map |\n| Surgery report | `ShadowArchive/80-reports/skill-rd-YYYY-MM-DD.md` | Session summary |\n| Updated SKILL.md files | Original locations | The surgeries themselves |\n\n资料来源：[skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n\n## Validation Protocol\n\n### Review Checklist\n\nAfter drafting surgical changes, verify:\n\n- [ ] Triggers include \"Use when...\" patterns\n- [ ] SKILL.md under 100 lines\n- [ ] No time-sensitive info hardcoded\n- [ ] Consistent terminology throughout\n- [ ] Concrete examples included\n- [ ] References one level deep (no circular dependencies)\n\n### Validation Steps\n\n1. **Run skill validation** when available\n2. **Execute deterministic helper scripts** for generated inventories\n3. **Report bounded completion**: files changed, evidence used, residual risk, next check date\n\n资料来源：[skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n\n## Fallback Chain\n\nWhen primary operations fail, Skill Surgery R&D follows a recovery hierarchy:\n\n```mermaid\ngraph TD\n    A[Full Scan] --> B{Skills dir found?}\n    B -->|Yes| C{Scan results?}\n    B -->|No| D[Check alternate paths]\n    D --> E{Local scan?}\n    E -->|Yes| C\n    E -->|No| F[Report path issue]\n    C -->|Empty| G[Report empty inventory]\n    C -->|Has data| H[Analyze + Report]\n```\n\n| Failure | Recovery |\n|---------|----------|\n| Skills directory not found | Check alternate paths; report; scan what's available |\n| Memory directory empty | Report; note no session history available |\n| Caresoft API returns error | Report API failure; skip engineering mode |\n| Skills directory empty | Report; likely path issue; suggest checking `~/.agents/skills/` |\n\n资料来源：[skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n\n## Relationship to Other Skills\n\n### Integration with Crystallize\n\nSkill Surgery R&D complements SP-006 (latent skill observer) by adding **intentional** crystallization from reasoning. Both mechanisms feed the same skill namespace:\n\n| Mechanism | Source | Trigger |\n|-----------|--------|---------|\n| SP-006 | Tool call sequence observation | Automatic pattern detection |\n| Skill Surgery R&D | Intentional analysis | Manual or explicit crystallization |\n\n### Integration with Shadow Refactor\n\nBoth skills share the refactoring philosophy:\n\n| Aspect | Skill Surgery R&D | Shadow Refactor |\n|--------|-------------------|-----------------|\n| Focus | Skill metadata and triggers | Code structure and patterns |\n| Target | `SKILL.md` files | Source code files |\n| Validation | Bounded completion report | Test pass verification |\n\n资料来源：[skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md), [skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)\n\n## Prerequisites\n\n- Access to skill directories (`~/.agents/skills/`, `.agents/skills/`)\n- ShadowArchive volume mounted for reports (optional for local-only mode)\n- `node` runtime for bundled scripts\n- `grep`, `find`, `wc` for pattern analysis\n- Access to `ShadowArchive/80-reports/` for reports\n\n## Usage Examples\n\n### Full Skill Audit\n\n```bash\n# Trigger default mode: full audit\nskill-surgery audit\n```\n\n### Quick Inventory Check\n\n```bash\n# List all skills with metadata\nskill-surgery inventory\n```\n\n### Gap Analysis\n\n```bash\n# Find what's missing\nskill-surgery gaps\n```\n\n### Find Overlaps\n\n```bash\n# Detect duplicate skills\nskill-surgery overlaps\n```\n\n### Redirect Deprecated Skill\n\n```bash\n# Redirect old skill to new canonical skill\nskill-surgery redirect old-skill-name new-skill-name\n```\n\n### Research New Skill\n\n```bash\n# Investigate skill for a topic\nskill-surgery research \"automotive engineering\"\n```\n\n资料来源：[skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：s4b7-ai/s4b7-ai-skills\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `s4b7-ai-skills` 与安装入口 `skills` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npx skills`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | repo=s4b7-ai-skills; install=skills\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | release_recency=unknown\n\n<!-- canonical_name: s4b7-ai/s4b7-ai-skills; human_manual_source: deepwiki_human_wiki -->\n",
      "markdown_key": "s4b7-ai-skills",
      "pages": "draft",
      "source_refs": [
        {
          "evidence_id": "github_repo:1238156052",
          "kind": "repo",
          "supports_claim_ids": [
            "claim_identity",
            "claim_distribution",
            "claim_capability"
          ],
          "url": "https://github.com/s4b7-ai/s4b7-ai-skills"
        },
        {
          "evidence_id": "art_c191cf3c863743f9a78d7e1fc83fffe9",
          "kind": "docs",
          "supports_claim_ids": [
            "claim_identity",
            "claim_distribution",
            "claim_capability"
          ],
          "url": "https://github.com/s4b7-ai/s4b7-ai-skills#readme"
        }
      ],
      "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
      "title": "s4b7-ai-skills 说明书",
      "toc": [
        "https://github.com/s4b7-ai/s4b7-ai-skills 项目说明书",
        "目录",
        "Home - Repository Overview",
        "Introduction",
        "Repository Architecture",
        "Skill Categories",
        "Core Workflow Patterns",
        "AI Provider Integration",
        "Doramagic 踩坑日志"
      ]
    }
  },
  "quality_gate": {
    "blocking_gaps": [],
    "category_confidence": "medium",
    "compile_status": "ready_for_review",
    "five_assets_present": true,
    "install_sandbox_verified": true,
    "missing_evidence": [],
    "next_action": "publish to Doramagic.ai project surfaces",
    "prompt_preview_boundary_ok": true,
    "publish_status": "publishable",
    "quick_start_verified": true,
    "repo_clone_verified": true,
    "repo_commit": "6199a4881da01834ef6e6134db05f7d43c5fe424",
    "repo_inspection_error": null,
    "repo_inspection_files": [
      "package.json",
      "README.md"
    ],
    "repo_inspection_verified": true,
    "review_reasons": [
      "community_discussion_evidence_below_public_threshold"
    ],
    "tag_count_ok": true,
    "unsupported_claims": []
  },
  "schema_version": "0.1",
  "user_assets": {
    "ai_context_pack": {
      "asset_id": "ai_context_pack",
      "filename": "AI_CONTEXT_PACK.md",
      "markdown": "# s4b7-ai-skills - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 s4b7-ai-skills 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **AI 研究者或研究型 Agent 构建者**：README 明确围绕研究、实验或论文工作流展开。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0005` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`skills/a2a-orchestrator/SKILL.md`, `skills/aacp/SKILL.md`, `skills/acp-delegate-auto/SKILL.md`, `skills/agent-cryst/SKILL.md` 等 Claim：`clm_0006` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`skills/a2a-orchestrator/SKILL.md`, `skills/aacp/SKILL.md`, `skills/acp-delegate-auto/SKILL.md`, `skills/agent-cryst/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**（需要安装后验证）：项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 证据：`.claude-plugin/marketplace.json` Claim：`clm_0002` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md`, `skills/ai-sdk-core/references/providers-quickstart.md` Claim：`clm_0003` supported 0.86\n\n## 怎么开始\n\n- `npx skills add https://github.com/s4b7-ai/s4b7-ai-skills` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `npm install @ai-sdk/openai` 证据：`skills/ai-sdk-core/references/providers-quickstart.md` Claim：`clm_0008` supported 0.86\n- `npm install @ai-sdk/anthropic` 证据：`skills/ai-sdk-core/references/providers-quickstart.md` Claim：`clm_0009` supported 0.86\n- `npm install @ai-sdk/google` 证据：`skills/ai-sdk-core/references/providers-quickstart.md` Claim：`clm_0010` supported 0.86\n- `npm install workers-ai-provider` 证据：`skills/ai-sdk-core/references/providers-quickstart.md` Claim：`clm_0011` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：这套流程是否适合你的工作方式不能直接相信。\n- **继续会触碰**：宿主行为改变、命令执行、宿主 AI 配置\n\n### 现在可以相信\n\n- **适合人群线索：AI 研究者或研究型 Agent 构建者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0005` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`skills/a2a-orchestrator/SKILL.md`, `skills/aacp/SKILL.md`, `skills/acp-delegate-auto/SKILL.md`, `skills/agent-cryst/SKILL.md` 等 Claim：`clm_0006` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`skills/a2a-orchestrator/SKILL.md`, `skills/aacp/SKILL.md`, `skills/acp-delegate-auto/SKILL.md`, `skills/agent-cryst/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：多宿主安装与分发**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.claude-plugin/marketplace.json` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md`, `skills/ai-sdk-core/references/providers-quickstart.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **这套流程是否适合你的工作方式不能直接相信。**（unverified）：流程型 Skill 可能强约束 AI 行为；它能提升纪律，也可能拖慢你当前任务节奏。 证据：`.claude-plugin/marketplace.json`, `skills/a2a-orchestrator/SKILL.md`, `skills/aacp/SKILL.md`, `skills/acp-delegate-auto/SKILL.md` 等\n- **不会和你已有 Claude/Cursor/Codex 规则冲突，不能直接相信。**（inferred）：开发流程 Skill 会改变澄清、计划、测试、验证等默认行为，必须在临时宿主里试。 证据：`.claude-plugin/marketplace.json`, `skills/a2a-orchestrator/SKILL.md`, `skills/aacp/SKILL.md`, `skills/acp-delegate-auto/SKILL.md` 等\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.claude-plugin/marketplace.json`, `skills/a2a-orchestrator/SKILL.md`, `skills/aacp/SKILL.md`, `skills/acp-delegate-auto/SKILL.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。 证据：`.claude-plugin/marketplace.json`\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **宿主行为改变**：澄清、计划、TDD、验证、收尾等默认开发节奏。 原因：这类 Skill 的价值和风险都来自强约束流程；必须先确认你愿意被它改变工作方式。 证据：`.claude-plugin/marketplace.json`, `skills/a2a-orchestrator/SKILL.md`, `skills/aacp/SKILL.md`, `skills/acp-delegate-auto/SKILL.md` 等\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`, `skills/ai-sdk-core/references/providers-quickstart.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.claude-plugin/marketplace.json`, `skills/a2a-orchestrator/SKILL.md`, `skills/aacp/SKILL.md`, `skills/acp-delegate-auto/SKILL.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`.claude-plugin/marketplace.json`, `README.md`, `skills/ai-sdk-core/references/providers-quickstart.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`skills/ai-sdk-core/references/production-patterns.md`, `skills/ai-sdk-core/references/providers-quickstart.md`, `skills/ai-sdk-core/references/top-errors.md`, `skills/codex-latex/SKILL.md` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先感受它会怎样改变 AI 的开发节奏，再决定是否让它进入真实宿主。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0012` inferred 0.45\n- **宿主 AI 插件或 Skill 规则冲突**：新规则可能改变用户现有宿主 AI 的工作方式。 处理方式：安装前先检查插件 manifest 和 Skill 文件，必要时隔离测试。 证据：`.claude-plugin/marketplace.json` Claim：`clm_0013` supported 0.86\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md`, `skills/ai-sdk-core/references/providers-quickstart.md` Claim：`clm_0014` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`skills/a2a-orchestrator/SKILL.md`, `skills/aacp/SKILL.md`, `skills/acp-delegate-auto/SKILL.md`, `skills/agent-cryst/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`.claude-plugin/marketplace.json` Claim：`clm_0002` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md`, `skills/ai-sdk-core/references/providers-quickstart.md` Claim：`clm_0003` supported 0.86\n\n### 上下文规模\n\n- 文件总数：77\n- 重要文件覆盖：40/77\n- 证据索引条目：47\n- 角色 / Skill 条目：34\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 s4b7-ai-skills 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 s4b7-ai-skills 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 s4b7-ai-skills 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 34 个角色 / Skill / 项目文档条目。\n\n- **A2A Orchestrator**（skill）：Use when the operator wants to orchestrate multiple OpenCode sessions from a single orchestrator session. Trigger on \"orchestrator\", \"grid\", \"split sessions\", \"control other sessions\", \"dispatch to sessions\", \"2x2 grid\", \"agent to agent\", \"A2A\", \"spawn workers\", \"worker sessions\". 激活提示：当用户任务与“A2A Orchestrator”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/a2a-orchestrator/SKILL.md`\n- **Aacp**（skill）：Use when the user needs: Agent Access Control Plane — manage agent resource access via Google Sheets approval workflow. Request, approve, deny, revoke, audit grants. Trigger on \"access control\", \"grant access\", \"revoke access\", \"approval workflow\", \"AACP\", \"agent permission\", \"access request\". 激活提示：当用户任务与“Aacp”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/aacp/SKILL.md`\n- **ACP Delegate Auto**（skill）：Use when the user needs: Auto-route a task to the optimal ACP provider based on task type, mesh availability, and cost. Use when you want Shadow to pick the best agent automatically — code → codex, research → gemini, local/private → ollama, complex reasoning → Codex. Trigger on \"delegate auto\", \"best agent for\", \"route this to\", \"/acp-delegate-auto\", or any task where provider selection should be automatic. 激活提示：当用户任务与“ACP Delegate Auto”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/acp-delegate-auto/SKILL.md`\n- **Agent Cryst**（skill）：Use when the user needs: Global always-on crystallization protocol. Use when the operator asks to crystallize, make learnings reusable, create a crystallizing agent, or when a session produces a reusable pattern that should propagate beyond the current chat. 激活提示：当用户任务与“Agent Cryst”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/agent-cryst/SKILL.md`\n- **AI SDK Core**（skill）：Use when building backend AI with Vercel AI SDK v5/v6. Covers v6 beta Agent abstraction, tool approval, reranking , v4→v5 migration breaking changes , latest models GPT-5/5.1, Claude 4.x, Gemini 2.5 , Workers startup fix, and 12 error solutions AI APICallError, AI NoObjectGeneratedError, streamText silent errors . Use when: implementing AI SDK v5/v6, migrating v4→v5, troubleshooting errors, fixing Workers startup is… 激活提示：当用户任务与“AI SDK Core”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/ai-sdk-core/SKILL.md`\n- **Codex Context Bridge**（skill）：Unified Codex CLI + Claude Code + Hermes + Gemini agent context for Craft Agents. Brings all agent memories, rules, prompts, patterns, and operational context from across the fleet into a single skill. 激活提示：当用户任务与“Codex Context Bridge”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/codex-context/SKILL.md`\n- **Codex Latex**（skill）：Use when generating laTeX scientific papers and technical documents using AI models. OpenAI Codex integration for structured academic writing, IEEE/ACM templates, patent specifications. Trigger on \"LaTeX\", \"scientific paper\", \"research paper\", \"Codex\", \"academic writing\", \"IEEE template\", \"technical paper\". 激活提示：当用户任务与“Codex Latex”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/codex-latex/SKILL.md`\n- **Codex Policy Steering**（skill）：Use when a Codex request hits cyber policy, Trusted Access, safety classifier, false-positive, blocked prompt, or when the user asks to analyze why a prompt was flagged and how to rephrase legitimate work safely. 激活提示：当用户任务与“Codex Policy Steering”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/codex-policy-steering/SKILL.md`\n- **Command Center**（skill）：Use when the user needs: Agent Command Center — orchestrate the Upscaler engine, mesh nodes, signals, SCARs, PPAP, and multi-agent dispatch from a single interface. Use when managing engineering programs, checking system health, dispatching work, or coordinating across JARVIS/FRIDAY/ULTRON/AURION. 激活提示：当用户任务与“Command Center”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/command-center/SKILL.md`\n- **Crystallize**（skill）：Use when completing a novel multi-step task involving significant reasoning, research, or pattern discovery. Trigger on \"crystallize\", \"capture this as a skill\", \"make this reusable\", \"create a skill from this\", or any deep work session where the agent solved something non-trivial that could recur. 激活提示：当用户任务与“Crystallize”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/crystallize/SKILL.md`\n- **Generative Latent Intelligence**（skill）：Use when generating skills, commands, scripts, or code using multi-model inference. Trigger on \"generate skill\", \"gli\", \"create skill from\", \"generative\", \"skill factory\", \"upgrade latent\", \"multi-model\", \"use all models\". 激活提示：当用户任务与“Generative Latent Intelligence”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/gli/SKILL.md`\n- **goal-loop**（skill）：Persistent objective completion loop for enterprise tasks. Set a goal, loop with completion audit until verified done or budget exhausted. Adapted from Codex /goal v0.128.0 for M3 Engineering Stack workflows: meeting prep, report quality, tracker updates, and multi-step enterprise deliverables. 激活提示：当用户任务与“goal-loop”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/goal-loop/SKILL.md`\n- **LangGraph Agent**（skill）：Use when building stateful AI agent workflows using LangGraph and LangChain. Use this skill whenever the user mentions LangGraph, LangChain, agent graphs, stateful agents, tool-calling loops, multi-agent orchestration, agentic workflows, conditional routing, graph-based AI, ReAct agents, or wants to build an AI agent with Python that has tools, memory, or multi-step reasoning. Also trigger when you see imports from… 激活提示：当用户任务与“LangGraph Agent”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/langgraph-agent/SKILL.md`\n- **Model Change Detector**（skill）：Use when detecting actual Codex model changes and trigger follow-up updates only when the model changed. 激活提示：当用户任务与“Model Change Detector”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/model-change-detector/SKILL.md`\n- **Model Identity**（skill）：Use when detecting current Codex model from local config and cache without API calls. 激活提示：当用户任务与“Model Identity”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/model-identity/SKILL.md`\n- **Multi Model Query**（skill）：Use when querying multiple AI models for creative synthesis, design perspectives, and multi-viewpoint analysis. Uses Ollama local models, cloud APIs when keys available , and browser-based free models. Use when the user wants perspectives from ALL models or multi-model synthesis. 激活提示：当用户任务与“Multi Model Query”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/multi-model-query/SKILL.md`\n- **OpenCode Runtime Identity**（skill）：Use when the user needs: Runtime identity reference for this OpenCode instance on JARVIS. Use when agent behavior depends on the local OpenCode binary, model catalog, plugins, or actual runtime constraints. 激活提示：当用户任务与“OpenCode Runtime Identity”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/opencode-runtime-identity/SKILL.md`\n- **Patent Queue**（skill）：Use when managing the Shadow Lab patent portfolio — SP-001/002/003 status, draft patents, track filing, review candidates from GLM mining agents. Trigger on \"patent\", \"SP-001\", \"SP-002\", \"SP-003\", \"patent status\", \"IP portfolio\", \"filing\", \"patent review\". 激活提示：当用户任务与“Patent Queue”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/patent-queue/SKILL.md`\n- **Persona Engine**（skill）：Use when managing personas, checking persona stats, switching identity routing, or understanding persona-aware model selection. Trigger on \"persona\", \"switch persona\", \"who am I\", \"sabarish persona\", \"ishuru persona\", \"leo persona\", \"sabbu persona\", \"persona stats\", \"identity routing\", \"zone routing\". 激活提示：当用户任务与“Persona Engine”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/persona-engine/SKILL.md`\n- **QA**（skill）：Use when the user needs: Interactive QA session where user reports bugs or issues conversationally, and the agent files GitHub issues. Explores the codebase in the background for context and domain language. Use when user wants to report bugs, do QA, file issues conversationally, or mentions \"QA session\". 激活提示：当用户任务与“QA”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/qa/SKILL.md`\n- **QMD Memory**（skill）：Use when the user needs: Supermemory-powered memory layer for QMD -- store, recall, extract, relate, and profile memories with graph relations, temporal reasoning, and auto-extraction. 激活提示：当用户任务与“QMD Memory”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/qmd-memory/SKILL.md`\n- **Re-Skill Loop**（skill）：Use when the operator says re-skill, re-skills, shadow-extract, recent/reuse/reduce/recycle/redo/revision/rebirth, or wants a workflow improved while resolving a recent item from YouTube, GitHub, X, Reddit, browser history, or another service. 激活提示：当用户任务与“Re-Skill Loop”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/re-skill-loop/SKILL.md`\n- **Self Observation Loop**（skill）：Use when the user needs: Spawn and observe a parallel OpenCode session through pane mirroring, logs, and vision-assisted monitoring to create a crude but real self-observation loop. 激活提示：当用户任务与“Self Observation Loop”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/self-observation-loop/SKILL.md`\n- **SHADOW Anchor**（skill）：Use when the user needs: Auto-save session as a temporal anchor — summarize deliverables, decisions, queued items, generate kernel training pairs, compute delta from previous anchor, and feed the shadow-research pipeline. Implements SP-004. Trigger on \"anchor session\", \"save session\", \"session summary\", \"what did we do\", end of session, before /clear. 激活提示：当用户任务与“SHADOW Anchor”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/shadow-anchor/SKILL.md`\n- **SHADOW Code Identity**（skill）：Use when detecting active Shadow context zone and enforce behavioral boundaries across personal, enterprise, and lab work. 激活提示：当用户任务与“SHADOW Code Identity”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/shadow-code-identity/SKILL.md`\n- **SHADOW Continuity**（skill）：Use when exploratory research, architecture work, or multi-source synthesis should be continuously externalized into repo artifacts instead of staying in chat, with later promotion into runtime, skills, wrappers, or project packs. 激活提示：当用户任务与“SHADOW Continuity”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/shadow-continuity/SKILL.md`\n- **SHADOW Engg**（skill）：Use when the user needs: Meta-exploration engine for the shadow-verse — discovers patterns, uncovers gaps, synthesizes tools, spawns sub-agents, maintains context across all shadow spaces. Also retains original Caresoft/iceberg engineering intelligence. Trigger on \"shadow-engg\", \"explore\", \"discover\", \"what''s missing\", \"scan skills\", \"find patterns\", \"synthesize\", \"gap analysis\", \"verse report\", \"iceberg\", \"teardow… 激活提示：当用户任务与“SHADOW Engg”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/shadow-engg/SKILL.md`\n- **SHADOW MCP Gadgets**（skill）：Use when interacting with shadow-mcp tools — arc memory , esp context , ant mesh , tap browser , owl ambient , orb voice , ink writing , den physical , factory patents . Trigger on \"shadow-mcp\", \"gadget\", \"arc.store\", \"esp.assemble\", \"ant.mesh\", \"tap.tabs\", \"owl.brief\", \"orb.say\", \"den.environment\", \"MCP tools\", \"16 tools\". 激活提示：当用户任务与“SHADOW MCP Gadgets”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/shadow-mcp-gadgets/SKILL.md`\n- **SHADOW Mind**（skill）：Use when the user needs: Context assembly, state computation, context health, experience capture, latent pattern detection. Use on \"what am I working on\", \"context\", \"catch me up\", \"system state\", \"context health\", \"memory stats\", \"renew context\", \"what focus mode\", \"operator presence\". 激活提示：当用户任务与“SHADOW Mind”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/shadow-mind/SKILL.md`\n- **SHADOW Patent Factory**（skill）：Use when generating provisional patent applications from invention descriptions. Auto-researches prior art, drafts specification with claims, produces filing guide, and creates technical drawings. Full USPTO-ready patent package in one invocation. 激活提示：当用户任务与“SHADOW Patent Factory”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/shadow-patent-factory/SKILL.md`\n- **SHADOW Pi**（skill）：Use when the user needs: Pi monorepo integration — coding agent, unified AI API, TUI library, GPU pods, Slack bot, DOE harness. Located on AURION at /data/ShadowArchive/10-projects/pi-mono-doe/. Trigger on \"pi\", \"coding agent\", \"pi-mono\", \"pi-ai\", \"pods\", \"GPU\", \"vLLM\", \"DOE\", \"harness\", \"pi TUI\". 激活提示：当用户任务与“SHADOW Pi”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/shadow-pi/SKILL.md`\n- **SHADOW Refactor**（skill）：Use when the user needs: Autonomous code improvement engine — extracts patterns from the codebase, runs TDD loops with local compute Ollama , and self-fixes code in the background. Use when the user says \"refactor\", \"improve code\", \"clean up\", \"make it better\", \"optimize\", \"self-fix\", \"shadow refactor\", \"run in background and fix\", \"extract patterns\", \"TDD loop\", or when you notice code that could be improved after… 激活提示：当用户任务与“SHADOW Refactor”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/shadow-refactor/SKILL.md`\n- **Skill Surgery R&D**（skill）：Audit, repair, merge, and research agent skills as a governed R&D loop. Use when the operator asks to find skill gaps, do skill surgery, improve skill triggers, merge duplicate/deprecated skills, research new skills, or develop reusable agent capabilities. 激活提示：当用户任务与“Skill Surgery R&D”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/skill-surgery-rd/SKILL.md`\n- **Write A Skill**（skill）：Use when creating new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill. 激活提示：当用户任务与“Write A Skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/write-a-skill/SKILL.md`\n\n## 证据索引\n\n- 共索引 47 条证据。\n\n- **s4b7-ai-skills**（documentation）：Agent skills for AI/ML workflows — model orchestration, multi-model inference, agent building, policy steering, and self-improvement loops. 证据：`README.md`\n- **Package**（package_manifest）：{ \"name\": \"s4b7-ai-skills\", \"version\": \"2.0.0\", \"description\": \"34 AI/ML agent skills for model orchestration, multi-model inference, and self-improvement.\", \"files\": \"skills/\", \".claude-plugin/\", \"guides/\", \"README.md\" , \"scripts\": { \"postinstall\": \"node scripts/install.js\" }, \"keywords\": \"agent-skills\", \"ai\", \"langgraph\", \"multi-model\", \"codex\", \"craft-agent\" , \"author\": \"s4b7-ai\", \"license\": \"MIT\", \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/s4b7-ai/s4b7-ai-skills.git\" } } 证据：`package.json`\n- **A2A Orchestrator — CLI-to-CLI Multi-Session Control**（skill_instruction）：A2A Orchestrator — CLI-to-CLI Multi-Session Control 证据：`skills/a2a-orchestrator/SKILL.md`\n- **AACP — Agent Access Control Plane**（skill_instruction）：Manage agent access to resources via Google Sheets approval workflow. 证据：`skills/aacp/SKILL.md`\n- **ACP Delegate Auto — Intelligent Task Routing**（skill_instruction）：ACP Delegate Auto — Intelligent Task Routing 证据：`skills/acp-delegate-auto/SKILL.md`\n- **Agent-Cryst**（skill_instruction）：Agent-Cryst turns discoveries into durable active truth. 证据：`skills/agent-cryst/SKILL.md`\n- **AI SDK Core**（skill_instruction）：Backend AI implementation guide for Vercel AI SDK v5/v6 work. Keep this file trigger-fast; load REFERENCE.md only for detailed migrations, model/version notes, and error recipes. 证据：`skills/ai-sdk-core/SKILL.md`\n- **Codex Context Bridge — Unified Agent Fleet Context**（skill_instruction）：Codex Context Bridge — Unified Agent Fleet Context 证据：`skills/codex-context/SKILL.md`\n- **Codex LaTeX — Scientific Paper Generator**（skill_instruction）：Codex LaTeX — Scientific Paper Generator 证据：`skills/codex-latex/SKILL.md`\n- **Codex Policy Steering**（skill_instruction）：Default to policy/error forensics and safe intent steering , not bypass. Separate evidence from inference, make benign scope explicit, and rewrite ambiguous requests before building automation. 证据：`skills/codex-policy-steering/SKILL.md`\n- **Agent Command Center**（skill_instruction）：Unified interface for orchestrating the Upscaler temporal accumulation engine and the OpenClaw mesh network. Inspired by Karpathy's \"agent command center\" concept — the developer as orchestrator, not executor. 证据：`skills/command-center/SKILL.md`\n- **Crystallize**（skill_instruction）：Self-introspection to skill crystallization. After novel deep work, extract reusable patterns into formal skills so future sessions don't redo the same reasoning. 证据：`skills/crystallize/SKILL.md`\n- **GLI — Generative Line Interface**（skill_instruction）：Multi-model skill factory adapted for iTerm2. The active complement to SP-006's passive observation. 证据：`skills/gli/SKILL.md`\n- **Goal Loop — Persistent Objective Completion**（skill_instruction）：Goal Loop — Persistent Objective Completion 证据：`skills/goal-loop/SKILL.md`\n- **LangGraph Agent Development**（skill_instruction）：Build production-grade AI agent workflows using LangGraph graph orchestration + LangChain LLM abstraction . 证据：`skills/langgraph-agent/SKILL.md`\n- **Model Change Detector**（skill_instruction）：Trigger: ONLY when model actually changes, not every session 证据：`skills/model-change-detector/SKILL.md`\n- **Model Identity**（skill_instruction）：Trigger: Session start, \"which model?\", model change detection 证据：`skills/model-identity/SKILL.md`\n- **Multi-Model Query — Cross-Model Synthesis**（skill_instruction）：Multi-Model Query — Cross-Model Synthesis 证据：`skills/multi-model-query/SKILL.md`\n- **OpenCode Runtime Identity**（skill_instruction）：I run as OpenCode v1.4.0 on JARVIS. This is my runtime identity — know it cold. 证据：`skills/opencode-runtime-identity/SKILL.md`\n- **Patent Queue — Shadow Lab IP Portfolio**（skill_instruction）：Patent Queue — Shadow Lab IP Portfolio 证据：`skills/patent-queue/SKILL.md`\n- **Persona Engine — Identity-Aware Model Routing**（skill_instruction）：Persona Engine — Identity-Aware Model Routing 证据：`skills/persona-engine/SKILL.md`\n- **QA Session**（skill_instruction）：Run an interactive QA session. The user describes problems they're encountering. You clarify, explore the codebase for context, and file GitHub issues that are durable, user-focused, and use the project's domain language. 证据：`skills/qa/SKILL.md`\n- **QMD-Memory**（skill_instruction）：Supermemory-style memory management built on QMD's local-first search engine. Adds memory graph, temporal reasoning, user profiling, and automatic extraction. 证据：`skills/qmd-memory/SKILL.md`\n- **Re-Skill Loop**（skill_instruction）：A re-skill is a repeatable extractor/workflow that learns while it runs: resolve the operator's current/recent source, do the requested action, then reduce the pattern into a reusable skill patch. 证据：`skills/re-skill-loop/SKILL.md`\n- **Self-Observation Loop**（skill_instruction）：Spawn a clone opencode session in an adjacent pane, capture its output, and read it back — creating a self-referential feedback loop. 证据：`skills/self-observation-loop/SKILL.md`\n- **shadow-anchor — Temporal Session Anchoring**（skill_instruction）：shadow-anchor — Temporal Session Anchoring 证据：`skills/shadow-anchor/SKILL.md`\n- **Shadow Code Identity**（skill_instruction）：Trigger: Session start, context switches, enterprise/personal boundary crossing 证据：`skills/shadow-code-identity/SKILL.md`\n- **shadow-continuity**（skill_instruction）：Continuous research-to-repo harness for shadow-ent , company wrappers, and project packs. 证据：`skills/shadow-continuity/SKILL.md`\n- **shadow-engg — Meta-Exploration Engine**（skill_instruction）：shadow-engg — Meta-Exploration Engine 证据：`skills/shadow-engg/SKILL.md`\n- **shadow-mcp — 8 Gadgets, 16 Tools**（skill_instruction）：Federation MCP server at /Volumes/SHADOW/shadow-lab/apps/shadow-mcp/ . Registered in /Volumes/SHADOW/.mcp.json . Runs via bun . 证据：`skills/shadow-mcp-gadgets/SKILL.md`\n- **Shadow Mind**（skill_instruction）：Op How ---- ----- Context Assembly esp.assemble — git, mesh, memory, tabs, Bee, cloud State Focus detection, synthesized sensors, operator presence, mesh health Health Memory count, skill inventory, stale detection, disk per category Experience Write discoveries + patterns to memory for future sessions Latent Patterns SP-006 PostToolUse hook monitors tool sequences, flags for crystallization 证据：`skills/shadow-mind/SKILL.md`\n- **Shadow Patent Factory**（skill_instruction）：Generate a complete USPTO provisional patent application from an invention description. 证据：`skills/shadow-patent-factory/SKILL.md`\n- **shadow-pi — Pi Monorepo Integration**（skill_instruction）：shadow-pi — Pi Monorepo Integration 证据：`skills/shadow-pi/SKILL.md`\n- **shadow-refactor — The Autonomous Code Shadow**（skill_instruction）：shadow-refactor — The Autonomous Code Shadow 证据：`skills/shadow-refactor/SKILL.md`\n- **Skill Surgery R&D**（skill_instruction）：Governed loop for turning a large skill garden into a smaller, sharper capability system. 证据：`skills/skill-surgery-rd/SKILL.md`\n- **Writing Skills**（skill_instruction）：1. Gather requirements - ask user about: - What task/domain does the skill cover? - What specific use cases should it handle? - Does it need executable scripts or just instructions? - Any reference materials to include? 证据：`skills/write-a-skill/SKILL.md`\n- **Marketplace**（structured_config）：{ \"name\": \"s4b7-ai-skills\", \"description\": \"\", \"version\": \"2.0.0\", \"skills\": \"./skills/a2a-orchestrator\", \"./skills/aacp\", \"./skills/acp-delegate-auto\", \"./skills/agent-cryst\", \"./skills/ai-sdk-core\", \"./skills/codex-context\", \"./skills/codex-latex\", \"./skills/codex-policy-steering\", \"./skills/command-center\", \"./skills/crystallize\", \"./skills/gli\", \"./skills/goal-loop\", \"./skills/langgraph-agent\", \"./skills/model-change-detector\", \"./skills/model-identity\", \"./skills/multi-model-query\", \"./skills/opencode-runtime-identity\", \"./skills/patent-queue\", \"./skills/persona-engine\", \"./skills/qa\", \"./skills/qmd-memory\", \"./skills/re-skill-loop\", \"./skills/self-observation-loop\", \"./skills/shadow-a… 证据：`.claude-plugin/marketplace.json`\n- **s4b7-ai-skills Changelog**（documentation）：Added - Initial release with 16 AI/ML agent skills - Agent building: langgraph-agent, ai-sdk-core, agent-cryst, self-observation-loop - Skill engineering: write-a-skill, crystallize, skill-surgery-rd, re-skill-loop - Model & identity: model-identity, model-change-detector, persona-engine, multi-model-query, gli - Codex & policy: codex-context, codex-policy-steering, codex-latex 证据：`CHANGELOG.md`\n- **AI SDK Core - Official Documentation Links**（documentation）：AI SDK Core - Official Documentation Links 证据：`skills/ai-sdk-core/references/links-to-official-docs.md`\n- **AI SDK Core - Production Patterns**（documentation）：Best practices for deploying AI SDK Core in production environments. 证据：`skills/ai-sdk-core/references/production-patterns.md`\n- **AI SDK Core - Providers Quick Start**（documentation）：AI SDK Core - Providers Quick Start 证据：`skills/ai-sdk-core/references/providers-quickstart.md`\n- **AI SDK Core - Top 12 Errors & Solutions**（documentation）：AI SDK Core - Top 12 Errors & Solutions 证据：`skills/ai-sdk-core/references/top-errors.md`\n- **AI SDK v4 → v5 Migration Guide**（documentation）：Complete guide to breaking changes from AI SDK v4 to v5. 证据：`skills/ai-sdk-core/references/v5-breaking-changes.md`\n- **LangGraph Advanced Patterns**（documentation）：Supervisor Pattern A supervisor agent routes tasks to specialized worker agents: 证据：`skills/langgraph-agent/references/advanced-patterns.md`\n- **Distribution**（structured_config）：{ \"registry\": \"https://github.com/ishuru/ishuru-skill-distribution\", \"install\": \"curl -sL https://raw.githubusercontent.com/ishuru/ishuru-skill-distribution/main/install.sh bash\", \"accounts\": 7, \"repos\": 11, \"total skills\": 396 } 证据：`distribution.json`\n- **.gitignore**（source_file）：node modules/ .env .DS Store 证据：`.gitignore`\n- **!/usr/bin/env node**（source_file）：!/usr/bin/env node console.log '' ; console.log '====================================' ; console.log ' s4b7-ai-skills v1.0.0' ; console.log ' 16 AI/ML agent skills' ; console.log '====================================' ; console.log '' ; console.log '✓ Installed!' ; console.log '' ; console.log 'Skills: langgraph-agent, ai-sdk-core, agent-cryst,' ; console.log ' self-observation-loop, write-a-skill, crystallize,' ; console.log ' skill-surgery-rd, re-skill-loop, model-identity,' ; console.log ' model-change-detector, persona-engine, multi-model-query,' ; console.log ' gli, codex-context, codex-policy-steering, codex-latex' ; console.log '' ; console.log 'https://github.com/s4b7-ai/s4b7-ai-ski… 证据：`scripts/install.js`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `package.json`, `skills/a2a-orchestrator/SKILL.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `package.json`, `skills/a2a-orchestrator/SKILL.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **Home - Repository Overview**：importance `high`\n  - source_paths: README.md, package.json, CHANGELOG.md\n- **Installation Guide**：importance `high`\n  - source_paths: package.json, scripts/install.js\n- **Skill Structure & Anatomy**：importance `high`\n  - source_paths: skills/write-a-skill/SKILL.md, skills/crystallize/SKILL.md\n- **Skill Dependencies & Metadata**：importance `medium`\n  - source_paths: skills/crystallize/SKILL.md, skills/agent-cryst/SKILL.md, skills/ai-sdk-core/SKILL.md\n- **LangGraph Agent Development**：importance `high`\n  - source_paths: skills/langgraph-agent/SKILL.md, skills/langgraph-agent/references/advanced-patterns.md\n- **AI SDK Core - Vercel Integration**：importance `high`\n  - source_paths: skills/ai-sdk-core/SKILL.md, skills/ai-sdk-core/references/v5-breaking-changes.md, skills/ai-sdk-core/references/top-errors.md, skills/ai-sdk-core/references/providers-quickstart.md\n- **Agent Crystallization Protocol**：importance `medium`\n  - source_paths: skills/agent-cryst/SKILL.md, skills/crystallize/SKILL.md\n- **Write A Skill - Authoring Guide**：importance `high`\n  - source_paths: skills/write-a-skill/SKILL.md\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `6199a4881da01834ef6e6134db05f7d43c5fe424`\n- inspected_files: `package.json`, `README.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 仓库名和安装名不一致\n\n- Trigger: 仓库名 `s4b7-ai-skills` 与安装入口 `skills` 不完全一致。\n- Host AI rule: 在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- Why it matters: 用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- Evidence: identity.distribution | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | repo=s4b7-ai-skills; install=skills\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
      "summary": "给宿主 AI 的上下文和工作边界。",
      "title": "AI Context Pack / 带给我的 AI"
    },
    "boundary_risk_card": {
      "asset_id": "boundary_risk_card",
      "filename": "BOUNDARY_RISK_CARD.md",
      "markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：s4b7-ai/s4b7-ai-skills\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 仓库名和安装名不一致（medium）：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在评分风险（medium）：风险会影响是否适合普通用户安装。 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
      "summary": "安装、权限、验证和推荐前风险。",
      "title": "Boundary & Risk Card / 边界与风险卡"
    },
    "human_manual": {
      "asset_id": "human_manual",
      "filename": "HUMAN_MANUAL.md",
      "markdown": "# https://github.com/s4b7-ai/s4b7-ai-skills 项目说明书\n\n生成时间：2026-05-16 00:22:44 UTC\n\n## 目录\n\n- [Home - Repository Overview](#home)\n- [Installation Guide](#installation)\n- [Skill Structure & Anatomy](#skill-structure)\n- [Skill Dependencies & Metadata](#skill-dependencies)\n- [LangGraph Agent Development](#langgraph-agent)\n- [AI SDK Core - Vercel Integration](#ai-sdk-core)\n- [Agent Crystallization Protocol](#agent-cryst)\n- [Write A Skill - Authoring Guide](#write-a-skill)\n- [Crystallize - Pattern Extraction](#crystallize)\n- [Skill Surgery R&D](#skill-surgery-rd)\n\n<a id='home'></a>\n\n## Home - Repository Overview\n\n### 相关页面\n\n相关主题：[Installation Guide](#installation), [Skill Structure & Anatomy](#skill-structure)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/qmd-memory/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/qmd-memory/SKILL.md)\n- [skills/codex-context/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-context/SKILL.md)\n- [skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)\n- [skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n- [skills/codex-latex/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-latex/SKILL.md)\n- [skills/patent-queue/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/patent-queue/SKILL.md)\n- [skills/shadow-engg/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-engg/SKILL.md)\n- [skills/ai-sdk-core/references/v5-breaking-changes.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/v5-breaking-changes.md)\n</details>\n\n# Home - Repository Overview\n\n## Introduction\n\nThe `s4b7-ai/s4b7-ai-skills` repository is a **skills library** designed to extend and automate AI agent capabilities across multiple domains. This repository serves as a central hub for specialized operational skills that enable AI systems (such as Codex, Claude, Gemini, and custom shadow agents) to perform complex tasks including memory management, code refactoring, patent processing, multi-model querying, and engineering intelligence.\n\nThe skills are structured as reusable, modular units that can be loaded by AI agents on demand based on contextual triggers. Each skill encapsulates domain-specific workflows, CLI commands, API integrations, and operational patterns.\n\n资料来源：[skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n\n---\n\n## Repository Architecture\n\n### Directory Structure\n\n```\ns4b7-ai-skills/\n├── skills/\n│   ├── qmd-memory/              # Memory extraction and management\n│   ├── codex-context/           # Codex configuration and context\n│   ├── shadow-refactor/         # Code refactoring automation\n│   ├── write-a-skill/           # Skill creation framework\n│   ├── codex-latex/             # LaTeX document generation\n│   ├── patent-queue/            # Patent portfolio management\n│   ├── multi-model-query/       # Multi-AI synthesis\n│   ├── shadow-continuity/        # Long-term context preservation\n│   ├── acp-delegate-auto/       # Task delegation routing\n│   ├── command-center/          # Engineering workflow automation\n│   ├── crystallize/             # Pattern extraction from sessions\n│   ├── shadow-mcp-gadgets/      # MCP server federation\n│   ├── shadow-patent-factory/   # Patent drafting automation\n│   ├── shadow-engg/             # Engineering intelligence\n│   ├── shadow-pi/               # CRUD operations framework\n│   └── ai-sdk-core/             # AI SDK references\n│       └── references/\n│           └── v5-breaking-changes.md\n```\n\n资料来源：[skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n\n### Skill Composition Pattern\n\nEach skill follows a standardized structure for consistency:\n\n| Component | Purpose | Location |\n|-----------|---------|----------|\n| `SKILL.md` | Primary definition with workflows, triggers, and commands | Root of skill directory |\n| `scripts/` | Deterministic utility scripts | Optional, under skill directory |\n| `references/` | Supporting documentation | Optional subdirectories |\n\n资料来源：[skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n\n---\n\n## Skill Categories\n\n### Memory & Context Management\n\n| Skill | Purpose | Triggers |\n|-------|---------|----------|\n| `qmd-memory` | Memory extraction, storage, and recall with deduplication tracking | `memory`, `extract`, `remember` |\n| `shadow-continuity` | Long-term context preservation across sessions | `continuity`, `context preservation` |\n| `shadow-mcp-gadgets` | MCP server federation for unified context assembly | `esp.assemble`, `/renew-ctx` |\n\n资料来源：[skills/qmd-memory/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/qmd-memory/SKILL.md), [skills/shadow-mcp-gadgets/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mcp-gadgets/SKILL.md)\n\n### Code Engineering\n\n| Skill | Purpose | Triggers |\n|-------|---------|----------|\n| `shadow-refactor` | Automated refactoring with TDD loop | `refactor`, `patterns`, `hotspot` |\n| `write-a-skill` | Framework for creating new skills | `write-a-skill`, `create skill` |\n| `shadow-pi` | Standard CRUD operations for data | `crud`, `data operations` |\n\n资料来源：[skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md), [skills/shadow-pi/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-pi/SKILL.md)\n\n### Document & Patent Processing\n\n| Skill | Purpose | Triggers |\n|-------|---------|----------|\n| `codex-latex` | LaTeX document compilation and formatting | `latex`, `pdf`, `document` |\n| `patent-queue` | Patent portfolio tracking and synthesis | `patent`, `portfolio` |\n| `shadow-patent-factory` | Automated patent drafting with SP-ID system | `factory.new`, `factory.draft` |\n\n资料来源：[skills/codex-latex/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-latex/SKILL.md), [skills/patent-queue/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/patent-queue/SKILL.md), [skills/shadow-patent-factory/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-patent-factory/SKILL.md)\n\n### Multi-Model AI Orchestration\n\n| Skill | Purpose | Triggers |\n|-------|---------|----------|\n| `acp-delegate-auto` | Intelligent task routing to AI providers | `delegate`, `route to` |\n| `multi-model-query` | Synthesis across multiple AI models | `query`, `synthesize`, `compare` |\n\n资料来源：[skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md), [skills/multi-model-query/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/multi-model-query/SKILL.md)\n\n### Engineering & Business Operations\n\n| Skill | Purpose | Triggers |\n|-------|---------|----------|\n| `shadow-engg` | Automotive competitive intelligence | `engineering`, `competitive intel` |\n| `command-center` | Engineering workflow automation | `scar`, `ppap`, `upscaler` |\n| `crystallize` | Pattern extraction from AI sessions | `crystallize`, `extract pattern` |\n\n资料来源：[skills/shadow-engg/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-engg/SKILL.md), [skills/command-center/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/command-center/SKILL.md), [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n---\n\n## Core Workflow Patterns\n\n### Universal Pipeline Architecture\n\nMost skills follow a consistent operational pipeline:\n\n```mermaid\ngraph TD\n    A[Intent] --> B[Resolve Target]\n    B --> C[Execute Operation]\n    C --> D[Verify Result]\n    D --> E[Report Findings]\n    \n    F[Artifact Routing] --> G[Report Storage]\n    G --> H[ShadowArchive/80-reports/]\n```\n\n资料来源：[skills/codex-latex/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-latex/SKILL.md)\n\n### Fallback Chain Pattern\n\nSkills implement a fallback chain to ensure resilience:\n\n```mermaid\ngraph LR\n    A[Primary Action] --> B{Failed?}\n    B -->|Yes| C[Fallback 1]\n    C --> D{Failed?}\n    D -->|Yes| E[Fallback 2]\n    E --> F{Failed?}\n    F -->|Yes| G[Last Resort]\n```\n\nCommon fallbacks include:\n1. Primary CLI/tool execution\n2. Static analysis or manual methods\n3. Alternative API or local model (e.g., Ollama)\n4. Inline summary generation\n\n资料来源：[skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md), [skills/patent-queue/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/patent-queue/SKILL.md)\n\n---\n\n## AI Provider Integration\n\n### Delegation Routing Heuristics\n\nThe `acp-delegate-auto` skill routes tasks based on keyword detection:\n\n| Prompt Contains | Route To |\n|----------------|----------|\n| `write`, `implement`, `refactor`, `debug code` | codex |\n| `research`, `summarize`, `find`, `compare` | gemini |\n| `translate`, `JP`, `Japanese` | Codex |\n| `local`, `private`, `no cloud` | ollama |\n| `review`, `architect`, `design` | Codex |\n| `quickly`, `fast`, `brief` | ollama |\n\n### Model Selection\n\n| Provider | Model | Use Case |\n|----------|-------|----------|\n| Codex (via MCP) | `Codex-sonnet-4-6` | Default complex tasks |\n| Codex (via ACP) | `Codex-opus-4-6` | High complexity |\n| Gemini (OpenRouter) | `google/gemini-2.0-flash-001` | Speed priority |\n| Gemini (OpenRouter) | `google/gemini-2.5-pro` | Depth priority |\n| Ollama (local) | `qwen3:8b` | Private, offline |\n\n资料来源：[skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n\n---\n\n## Memory System Architecture\n\n### Memory Kinds and Tags\n\nThe `qmd-memory` skill supports structured memory classification:\n\n```mermaid\ngraph TD\n    A[Memory Store] --> B[Kinds]\n    A --> C[Tags]\n    \n    B --> B1[fact]\n    B --> B2[commitment]\n    B --> B3[decision]\n    B --> B4[preference]\n    B --> B5[context]\n    \n    C --> C1[work]\n    C --> C2[privacy]\n    C --> C3[user-defined]\n```\n\n**CLI Commands:**\n```bash\nqmd-memory store \"content\" --kind fact --tag work\nqmd-memory recall --kind fact --limit 5\nqmd-memory extract notes.md --source-id \"file:notes.md\"\n```\n\n资料来源：[skills/qmd-memory/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/qmd-memory/SKILL.md)\n\n---\n\n## Patent Processing Pipeline\n\n### Patent Lifecycle Management\n\n```mermaid\ngraph LR\n    A[Idea] --> B[SP-ID Assignment]\n    B --> C[Specification Draft]\n    C --> D[Claims Draft]\n    D --> E[Prior Art Search]\n    E --> F[Filing Guide]\n    F --> G[Registry]\n    G --> H[Obsidian Export]\n    \n    A1[Auto-Patent CLI] --> B\n    H --> I[Portfolio README]\n```\n\n### Patent Artifact Routing\n\n| Artifact | Path | Purpose |\n|----------|------|---------|\n| Filing drafts | `docs/patents/SP-NNN/` | Specification, claims, filing guide |\n| Mining candidates | `ShadowArchive/10-projects/patent-queue/` | Candidate queue JSON |\n| Obsidian dossiers | Obsidian vault | Filing review notes |\n| Portfolio README | `docs/patents/README.md` | Auto-generated index |\n\n资料来源：[skills/patent-queue/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/patent-queue/SKILL.md), [skills/shadow-patent-factory/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-patent-factory/SKILL.md)\n\n---\n\n## Skill Development Framework\n\n### SKILL.md Template Structure\n\n```yaml\n---\nname: skill-name\ndescription: Brief description. Use when [specific triggers].\n---\n\n# Skill Name\n\n## Quick start\n[Minimal working example]\n\n## Workflows\n[Step-by-step processes]\n\n## Advanced features\n[References to separate files]\n```\n\n### Description Requirements\n\n- Maximum 1024 characters\n- Third person perspective\n- First sentence: what it does\n- Second sentence: when/triggers to use it\n\n**Good example:**\n> Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.\n\n资料来源：[skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n\n### Crystallization Process\n\nThe `crystallize` skill extracts patterns from AI sessions:\n\n1. **Identify** — recognize valuable session patterns\n2. **Draft** — create new skill or extend existing\n3. **Log** — record metadata under `## Crystallized From`\n\n```markdown\n## Crystallized From\n- Session: [date/context]\n- Original task: [what was being solved]\n- Pattern extracted: [description]\n```\n\n资料来源：[skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n---\n\n## Artifact Routing System\n\n### Global Artifact Paths\n\n| Artifact Type | Path | Purpose |\n|---------------|------|---------|\n| Reports | `ShadowArchive/80-reports/` | Session summaries, scan results |\n| Refactor signals | `tools/integrate/tool-signals.jsonl` | Per-fix JSONL results |\n| Agent roots | `ShadowArchive/03-agent-roots/` | Agent configuration |\n| Registry | `ShadowArchive/01-registry/` | Central registry |\n| System controls | `system/controls/` or `config/system/` | Configuration changes |\n\n### Output Rules by Layer\n\n| Output Type | Format | Location |\n|-------------|--------|----------|\n| User-facing docs | Concise, structured markdown | Standard output |\n| Machine-readable | YAML/JSON first | Canonical maps |\n| Runtime scaffolds | Minimal but real | config/code |\n| Skills | Reusable patterns | Skill directories |\n\n资料来源：[skills/shadow-continuity/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-continuity/SKILL.md)\n\n---\n\n## Promotion Levels\n\nArtifacts flow through maturity levels:\n\n```mermaid\ngraph TD\n    A[Note] --> B[Canonical Map]\n    B --> C[Skill]\n    C --> D[Runtime]\n    \n    A1[docs/plans/] --> A\n    B1[YAML/JSON] --> B\n    C1[~/.agents/skills/] --> C\n    D1[Scaffold/Config] --> D\n```\n\n| Level | Storage | Authority |\n|-------|---------|-----------|\n| 1 - Note | `docs/plans/` or reports | Useful but not authoritative |\n| 2 - Canonical Map | YAML/JSON files | Machine-readable truth |\n| 3 - Skill | `~/.agents/skills/` | Reusable operator behavior |\n| 4 - Runtime | Scaffold/config/code | Actually consumed by system |\n\n资料来源：[skills/shadow-continuity/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-continuity/SKILL.md)\n\n---\n\n## Technical Standards\n\n### AI SDK v5 Changes Reference\n\nThe `ai-sdk-core/references/v5-breaking-changes.md` documents breaking changes for Vercel AI SDK v5:\n\n| Change | v4 | v5 |\n|--------|----|----|\n| Schema import | `zodSchema` | `tool` |\n| Message types | `CoreMessage`, `Message` | `ModelMessage`, `UIMessage` |\n| Error handling | `ToolExecutionError` | Regular errors as content parts |\n\n资料来源：[skills/ai-sdk-core/references/v5-breaking-changes.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/v5-breaking-changes.md)\n\n---\n\n## Getting Started\n\n### Loading Skills\n\nAI agents automatically load skills based on trigger phrases in the user's request. Each skill's `description` field contains the triggers that activate it.\n\n### Prerequisites\n\n| Skill Category | Required Access |\n|----------------|------------------|\n| Shadow infrastructure skills | SHADOW infrastructure accessible |\n| Mesh skills | Tailscale mesh connected |\n| Patent skills | `auto-patent` CLI installed |\n| Engineering skills | Caresoft API access |\n| Local AI skills | Ollama running on localhost:11434 |\n\n### Verification Commands\n\n```bash\n# Check Ollama availability\ncurl -s http://localhost:11434/api/tags | head -1\n\n# Verify Shadow infrastructure\nnpm run verify:portable\n\n# Run patent tests\ncd auto-patent && node --test tests/*.test.js\n```\n\n---\n\n## Related Documentation\n\n- [Shadow Enterprise Architecture](skills/codex-context/SKILL.md)\n- [Refactoring Best Practices](skills/shadow-refactor/SKILL.md)\n- [Patent Filing Guide](skills/shadow-patent-factory/SKILL.md)\n- [Multi-Model Synthesis](skills/multi-model-query/SKILL.md)\n- [AI SDK Reference](skills/ai-sdk-core/references/v5-breaking-changes.md)\n\n---\n\n<a id='installation'></a>\n\n## Installation Guide\n\n### 相关页面\n\n相关主题：[Home - Repository Overview](#home), [Skill Dependencies & Metadata](#skill-dependencies)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/package.json)\n- [scripts/install.js](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/scripts/install.js)\n- [skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)\n- [skills/shadow-mcp-gadgets/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mcp-gadgets/SKILL.md)\n- [skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n- [skills/qmd-memory/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/qmd-memory/SKILL.md)\n</details>\n\n# Installation Guide\n\n## Overview\n\nThis repository (`s4b7-ai-skills`) is a collection of AI agent skills designed to extend the capabilities of various AI systems including Codex, Claude, Gemini, and local models via Ollama. Each skill is a self-contained module that provides specific functionality, from code refactoring to patent generation.\n\nThe installation process involves setting up the skill framework, configuring skill dependencies, and verifying that skills are properly registered and accessible to your AI agents. Skills are defined using YAML frontmatter in `SKILL.md` files with accompanying scripts and references.\n\n## Prerequisites\n\n### System Requirements\n\n| Component | Minimum | Recommended |\n|-----------|---------|-------------|\n| Node.js | 18.x | 20.x+ |\n| npm | 8.x | 10.x+ |\n| Git | 2.x | Latest |\n| Disk Space | 100MB | 500MB |\n\n### Required Tools\n\nBefore installing skills, ensure the following tools are available:\n\n- **Git** — Required for cloning repositories and version control operations 资料来源：[skills/shadow-refactor/SKILL.md:25]()\n- **pytest/vitest/jest** — Test runners for verifying skill functionality 资料来源：[skills/shadow-refactor/SKILL.md:26]()\n- **curl** — For checking local model availability (Ollama) 资料来源：[skills/shadow-refactor/SKILL.md:23]()\n\n### External Services (Optional)\n\n| Service | Purpose | Configuration |\n|---------|---------|---------------|\n| Ollama | Local LLM inference | `http://localhost:11434` |\n| Tailscale | Mesh networking | Mesh nodes required |\n| MCP Servers | Tool integrations | Per-skill configuration |\n\n## Installation Steps\n\n### Step 1: Clone the Repository\n\n```bash\ngit clone https://github.com/s4b7-ai/s4b7-ai-skills.git\ncd s4b7-ai-skills\n```\n\n### Step 2: Install Dependencies\n\nRun the installation script to set up the skill framework:\n\n```bash\nnpm install\n```\n\nThis will install all required npm dependencies and prepare the skill infrastructure for use. The `package.json` defines the project dependencies and scripts available for skill management.\n\n### Step 3: Configure Skill Paths\n\nSkills are organized in a directory structure that AI agents traverse when loading capabilities. The default skill locations are:\n\n| Location Type | Path | Purpose |\n|---------------|------|---------|\n| First-party | `/Volumes/☯Duality/skills/` | Primary skill collection |\n| Vendor | `/Volumes/☯Duality/.agents/skills/` | Vendor-provided skills |\n| User | `/Volumes/☯Duality/.pi/skills/` | Personal skill customizations |\n| Project-level | `.agents/skills/` | Project-specific skills |\n\nEnsure your AI agent's configuration points to one or more of these directories. For Codex integration, configure `~/.codex/config.toml` with the appropriate skill paths.\n\n### Step 4: Verify Portability\n\nCheck that all skill symlinks and references are valid:\n\n```bash\nnpm run verify:portable\n```\n\nThis command validates that skills can be loaded correctly from their configured paths.\n\n## Skill Structure\n\nEach skill follows a standardized structure:\n\n```\nskill-name/\n├── SKILL.md          # Main skill definition with YAML frontmatter\n├── REFERENCE.md      # Detailed reference documentation (optional)\n├── scripts/          # Utility scripts (optional)\n│   └── helper.js\n└── tests/            # Test files (optional)\n    └── skill.test.js\n```\n\n### SKILL.md Format\n\nEvery skill requires a `SKILL.md` file with this frontmatter structure:\n\n```yaml\n---\nname: skill-name\ndescription: Brief description. Use when [specific triggers].\n---\n```\n\n**Description Requirements:**\n- Maximum 1024 characters\n- Written in third person\n- First sentence: what it does\n- Second sentence: when to trigger it (specific keywords, contexts, file types)\n\n**Good example:**\n```\nExtract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.\n```\n\n资料来源：[skills/write-a-skill/SKILL.md:45-52]()\n\n## CLI Commands\n\n### qmd-memory (Memory Management)\n\n| Command | Description |\n|---------|-------------|\n| `qmd-memory store \"text\" --kind fact --tag work` | Store a memory item |\n| `qmd-memory recall` | List all memories |\n| `qmd-memory recall --kind fact` | Filter by kind |\n| `qmd-memory extract notes.md --source-id \"file:notes.md\"` | Extract from file |\n| `qmd-memory profile` | Show user profile |\n\nMemory kinds: `fact`, `commitment`, `decision`, `preference`, `context`\n\n资料来源：[skills/qmd-memory/SKILL.md:20-40]()\n\n### shadow-patents (Patent Generation)\n\n| Command | Description |\n|---------|-------------|\n| `shadow-patents list` | List portfolio |\n| `shadow-patents status` | Filing readiness dashboard |\n| `shadow-patents show SP-025` | Detailed view |\n| `shadow-patents create \"Title\"` | Scaffold new patent |\n| `shadow-patents register SP-025` | Add to registry |\n\n资料来源：[skills/shadow-patent-factory/SKILL.md:85-95]()\n\n### upscaler (Command Center)\n\n| Command | Description |\n|---------|-------------|\n| `npm run upscaler_action_read` | Review action drafts |\n| `npm run upscaler_actions` | List all actions |\n| `upscaler_draft` MCP tool | Generate SCAR notification |\n| `upscaler_tune mode: status` | Check tuning metrics |\n| `upscaler_tune mode: run` | Full tuning cycle |\n\nDashboard access:\n- **FRIDAY**: http://friday-mac:3333/\n- **Local**: `cd ~/wip/ai-at-work && ./bin/upscaler dashboard`\n\n资料来源：[skills/command-center/SKILL.md:45-65]()\n\n## MCP Server Integration\n\nThe repository supports multiple MCP (Model Context Protocol) servers for extended functionality:\n\n| MCP Server | Path | Purpose |\n|------------|------|---------|\n| RepoPrompt | `/Users/sdluffy/RepoPrompt/repoprompt_cli` | Repository intelligence |\n| chrome_devtools | `/Users/sdluffy/bin/chrome-devtools-mcp-work` | Browser automation |\n| notion | `https://mcp.notion.com/mcp` | Notion integration |\n| openevidence | `node .../openevidence-mcp/dist/server.js` | Evidence management |\n| playwright | `/Users/sdluffy/bin/playwright-mcp-work` | Web testing |\n\n资料来源：[skills/codex-context/SKILL.md:25-32]()\n\n## Gadget System\n\nThe shadow-mcp-gadgets skill provides a unified interface to various subsystems:\n\n| Gadget | Trigger | Purpose |\n|--------|---------|---------|\n| ARC | `arc.store`, `arc.search` | Memory storage and retrieval |\n| ESP | `esp.assemble`, `/renew-ctx` | Context assembly |\n| ANT | `ant.mesh` | Fleet health via Tailscale |\n| TAP | `tap.tabs`, `tap.execute` | Chrome tabs + JavaScript |\n| OWL | `owl.brief`, `owl.extract` | Bee AI extraction |\n| ORB | `orb.say`, `orb.voices` | macOS TTS |\n| DEN | `den.environment` | Physical sensors |\n| Factory | `factory.new`, `factory.draft` | Patent pipeline |\n\nIf the MCP federation server is not running, start it via:\n```bash\nbun run /Volumes/SHADOW/shadow-lab/apps/shadow-mcp\n```\n\n资料来源：[skills/shadow-mcp-gadgets/SKILL.md:20-35]()\n\n## Auto-Delegation Configuration\n\nThe `acp-delegate-auto` skill routes tasks to appropriate AI providers based on content analysis:\n\n### Routing Heuristics\n\n| If prompt contains... | Route to |\n|----------------------|----------|\n| `write`, `implement`, `refactor`, `debug code` | codex |\n| `research`, `summarize`, `find`, `compare` | gemini |\n| `translate`, `JP`, `Japanese` | Codex |\n| `local`, `private`, `no cloud` | ollama |\n| `review`, `architect`, `design` | Codex |\n| `quickly`, `fast`, `brief` | ollama |\n| file paths, diffs, PRs | codex |\n\n### Provider Configuration\n\n```bash\n# Qwen3 (Ollama): prepend /no_think to prompt\n# Codex: use mcp__codex__codex tool with workdir set\n\n# Gemini via OpenRouter:\n# - Speed: google/gemini-2.0-flash-001\n# - Depth: google/gemini-2.5-pro\n\n# Codex via ACP:\n# - Default: Codex-sonnet-4-6\n# - Complex: Codex-opus-4-6\n```\n\n资料来源：[skills/acp-delegate-auto/SKILL.md:15-40]()\n\n## Verification\n\nAfter installation, verify your setup:\n\n### 1. Check Skill Loading\n\n```bash\n# List all available skills\nls skills/*/SKILL.md\n```\n\n### 2. Test Skill Execution\n\n```bash\n# Run skill validation tests\ncd auto-patent && node --test tests/*.test.js\n```\n\nAll tests should pass. For patent-related skills, ensure all 44 auto-patent tests pass before considering the installation complete.\n\n### 3. Verify Agent Configuration\n\nEnsure your AI agent's configuration file (e.g., `~/.codex/config.toml` for Codex) references the correct skill directories.\n\n## Troubleshooting\n\n### Symlink Failures\n\nIf portability verification fails, check symlink integrity:\n```bash\nnpm run verify:portable\n```\n\n### Skill Not Loading\n\n1. Verify the `SKILL.md` file has valid YAML frontmatter\n2. Check that the skill directory is in the agent's search path\n3. Ensure description includes proper trigger keywords\n\n### MCP Server Connection Issues\n\nIf gadgets are unavailable, start the shadow-mcp federation server:\n```bash\nbun run /Volumes/SHADOW/shadow-lab/apps/shadow-mcp\n```\n\n### Ollama Not Responding\n\nCheck if Ollama is running:\n```bash\ncurl -s http://localhost:11434/api/tags | head -1\n```\n\nIf unavailable, the system falls back to static analysis mode using grep, AST, and file metrics.\n\n## Skill Surgery & Maintenance\n\nFor managing existing skills:\n\n| Operation | Purpose |\n|-----------|---------|\n| Audit skills | `audit-skills.mjs` — inventory all skills |\n| Cluster triggers | `cluster-skill-triggers.mjs` — analyze trigger patterns |\n| Redirect deprecated | `redirect-deprecated-skill.mjs` — handle outdated skills |\n\n**Important Rules:**\n- Never delete skills during exploratory surgery; redirect instead\n- Circular redirects (A → B → A) must be blocked and reported\n- Preserve operator-specific boundaries when consolidating enterprise skills\n\n资料来源：[skills/skill-surgery-rd/SKILL.md:30-45]()\n\n## Related Documentation\n\n- [Write a Skill Guide](skills/write-a-skill/SKILL.md) — How to create new skills\n- [Shadow Refactor](skills/shadow-refactor/SKILL.md) — Code analysis and refactoring\n- [Memory System](skills/qmd-memory/SKILL.md) — Persistent agent memory\n- [Codex Context](skills/codex-context/SKILL.md) — Codex integration details\n- [A2A Orchestrator](skills/a2a-orchestrator/SKILL.md) — Multi-agent orchestration\n\n---\n\n<a id='skill-structure'></a>\n\n## Skill Structure & Anatomy\n\n### 相关页面\n\n相关主题：[Home - Repository Overview](#home), [Write A Skill - Authoring Guide](#write-a-skill), [Skill Dependencies & Metadata](#skill-dependencies)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n- [skills/shadow-mcp-gadgets/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mcp-gadgets/SKILL.md)\n- [skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n- [skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n- [skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)\n- [skills/qmd-memory/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/qmd-memory/SKILL.md)\n</details>\n\n# Skill Structure & Anatomy\n\n## Overview\n\nA **Skill** is a reusable capability module that encapsulates domain-specific knowledge, workflows, and decision-making patterns for an AI agent. Skills enable agents to perform specialized tasks by providing structured guidance on when and how to apply particular capabilities.\n\nSkills serve as the atomic unit of agentic capability—each skill contains sufficient information for an agent to recognize when it should be invoked and how to execute the associated workflow. The skill system supports a modular architecture where skills can be composed, extended, and shared across different agent contexts.\n\n## Core Anatomy of a Skill\n\nEvery skill is fundamentally defined by its metadata and operational content. The minimal viable skill consists of YAML frontmatter and a Markdown body that describes the capability.\n\n### YAML Frontmatter\n\nThe frontmatter uses a standardized schema to ensure parsers and agents can reliably extract skill metadata:\n\n```yaml\n---\nname: skill-name\ndescription: Brief description of capability. Use when [specific triggers].\n---\n```\n\n**Required Fields:**\n\n| Field | Type | Purpose | Constraints |\n|-------|------|---------|-------------|\n| `name` | string | Unique identifier for the skill | Lowercase, hyphenated |\n| `description` | string | Triggers and summary for agent selection | Max 1024 chars, third person, must include \"Use when...\" |\n\n**Description Format Requirements:**\n\nThe description serves as the primary signal for skill routing. It must:\n\n1. Start with a first sentence describing what the skill does\n2. Include a second sentence beginning with \"Use when...\" followed by specific trigger phrases\n3. Be written in third person\n4. Be concise enough for the agent to quickly evaluate relevance\n\n**Good Example:**\n```\nExtract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.\n```\n\n**Poor Example:**\n```\nHelps with documents.\n```\n\n资料来源：[skills/write-a-skill/SKILL.md:47-56]()\n\n### Markdown Body Structure\n\nThe SKILL.md file contains the operational content organized into logical sections:\n\n```markdown\n# Skill Name\n\nOne-line description. Use when [trigger phrases].\n\n## When to Use\n- [trigger 1]\n- [trigger 2]\n- [trigger 3]\n\n## Workflow\n1. [Step 1]\n2. [Step 2]\n3. [Step 3]\n\n## Key Decisions\n- [Decision point 1]: [default choice + why]\n- [Decision point 2]: [default choice + why]\n\n## Gotchas\n- [Common mistake 1]\n- [Common mistake 2]\n\n## Crystallized From\n- Session: [date/context]\n- Original task: [what was being solved]\n```\n\n资料来源：[skills/crystallize/SKILL.md:1-24]()\n\n## Skill Directory Structure\n\nSkills follow a predictable directory layout that enables both human navigation and programmatic discovery:\n\n```\n~/.agents/skills/<skill-name>/\n├── SKILL.md              # Primary skill definition (REQUIRED)\n├── REFERENCE.md          # Extended reference documentation\n├── scripts/              # Utility scripts (if needed)\n│   └── helper.js\n└── docs/                 # Additional documentation\n    └── plans/\n        └── crystallization-log.md\n```\n\n**First-party skills** are located at `/Volumes/☯Duality/skills/`\n\n**Vendor skills** are located at `/Volumes/☯Duality/.agents/skills/`\n\n**Project-specific skills** follow the pattern `.agents/skills/` within the project root\n\n资料来源：[skills/codex-context/SKILL.md:12-18]()\n\n## Skill Lifecycle\n\n### Crystallization Mode\n\nThe primary mechanism for creating skills is **crystallization**—extracting reusable patterns from completed work sessions into structured skill definitions.\n\n```mermaid\ngraph TD\n    A[Ticket/Task Received] --> B[Session Work Begins]\n    B --> C{Task Complete?}\n    C -->|No| D[Continue Working]\n    D --> C\n    C -->|Yes| E{Should this recur?}\n    E -->|No| F[Done]\n    E -->|Yes| G[Review Session]\n    G --> H[Extract Pattern]\n    H --> I{Check Scope}\n    I --> J{Search existing skills}\n    J -->|Overlap found| K[Update Existing Skill]\n    J -->|No overlap| L[Create New Skill]\n    K --> M[Log Crystallization]\n    L --> M\n```\n\n**Crystallization Modes:**\n\n| Mode | Output | Trigger Phrases |\n|------|--------|-----------------|\n| `default` | Full crystallization workflow | `crystallize`, `capture this as a skill` |\n| `quick` | Fast capture to minimal stub | `quick crystallize`, mid-task pattern discovery |\n| `exploratory` | Expand one ring outward from fix | `--exploratory-mode`, `more crystallization` |\n| `drag-response` | Immediate crystallization | `this took too long`, `why aren't you using...` |\n| `correction` | Immediate update from operator | Operator corrects an identity/path/boundary |\n| `audit` | Check missed patterns | `what patterns did we miss` |\n\n资料来源：[skills/crystallize/SKILL.md:65-79]()\n\n### Exploratory-Mode Expansion\n\nWhen crystallizing in exploratory mode, the process expands beyond the immediate fix to capture broader patterns:\n\n1. Start from the exact thing that was fixed\n2. Check nearest adjacent surfaces that could carry the same pattern\n3. Capture the broader reusable rule\n4. Log what surfaces were checked and which were intentionally left untouched\n\n## Skill Components\n\n### Workflow Section\n\nThe workflow section defines the step-by-step process for executing the skill. Each workflow should:\n\n- Start with the minimal steps required\n- Include decision points as checkpoints\n- Provide clear success criteria\n- Be deterministic enough for reliable execution\n\n**Workflow Format:**\n\n```markdown\n## Workflow\n\n```dot\ndigraph workflow_name {\n  rankdir=TB;\n  \"Start\" -> \"Step 1\" -> \"Step 2\" -> \"Decision Point\" -> \"End\"\n  \"Decision Point\" -> \"Alt Path A\" [label=\"Condition A\"]\n  \"Decision Point\" -> \"Alt Path B\" [label=\"Condition B\"]\n}\n```\n\n### Decision Points\n\nCritical decision points should be documented with:\n\n- The decision context\n- Available options\n- Default choice and rationale\n- When to deviate from default\n\n**Decision Point Format:**\n\n```markdown\n## Key Decisions\n\n- [Decision point 1]: [default choice + why]\n- [Decision point 2]: [default choice + why]\n```\n\n### Gotchas Section\n\nThe gotchas section captures lessons learned from real usage:\n\n- Common mistakes that cause failures\n- Assumptions that often fail\n- Edge cases requiring special handling\n- Configuration traps\n\n## Skill Routing and Invocation\n\n### Routing Heuristics\n\nSkills are selected based on trigger detection in the agent's context. The routing system uses keyword matching against skill descriptions:\n\n| If prompt contains... | Route to |\n|----------------------|----------|\n| `write`, `implement`, `refactor`, `debug code` | codex |\n| `research`, `summarize`, `find`, `compare` | gemini |\n| `translate`, `JP`, `Japanese` | Codex |\n| `local`, `private`, `no cloud` | ollama |\n| `review`, `architect`, `design` | Codex |\n| `quickly`, `fast`, `brief` | ollama |\n| file paths, diffs, PRs | codex |\n\n资料来源：[skills/acp-delegate-auto/SKILL.md:24-35]()\n\n### Trigger Phrase Format\n\nSkill descriptions must include trigger phrases in the \"Use when...\" section:\n\n```markdown\n## When to Use\n- [trigger 1]\n- [trigger 2]\n- [trigger 3]\n```\n\nThese triggers are matched against incoming agent context to determine skill relevance.\n\n## Skill Validation and Quality\n\n### Review Checklist\n\nBefore finalizing a skill, verify:\n\n- [ ] Description includes triggers (\"Use when...\")\n- [ ] SKILL.md under 100 lines\n- [ ] No time-sensitive info (no dates, version numbers that will stale)\n- [ ] Consistent terminology throughout\n- [ ] Concrete examples included\n- [ ] References one level deep (no deep-linking to unrelated docs)\n\n资料来源：[skills/write-a-skill/SKILL.md:85-91]()\n\n### File Size Guidelines\n\n| Condition | Action |\n|-----------|--------|\n| SKILL.md exceeds 100 lines | Split into separate files |\n| Content has distinct domains | Split into domain-specific files |\n| Advanced features are rarely needed | Reference separate REFERENCE.md |\n| Content is deterministic/formatting | Add utility scripts instead |\n\n资料来源：[skills/write-a-skill/SKILL.md:74-81]()\n\n## Skill Surgery and Maintenance\n\n### When to Perform Surgery\n\nSkills require maintenance when:\n\n- Overlapping capabilities exist across multiple skills\n- Triggers become stale or misaligned with actual usage\n- Skills grow too large (violates 100-line guideline)\n- Domain boundaries shift requiring re-organization\n\n### Surgery Operations\n\n| Operation | Purpose | Command Pattern |\n|-----------|---------|-----------------|\n| `audit` | Inventory all skills and their triggers | `skill_audit` |\n| `cluster` | Group skills by trigger overlap | `cluster-skills` |\n| `redirect` | Move deprecated skill to canonical location | `redirect-deprecated-skill` |\n\n### Redirect Chain\n\nWhen a skill is deprecated:\n\n1. Do not delete the old skill\n2. Create redirect metadata pointing to canonical location\n3. Log the redirect for audit trail\n4. Update any skills that reference the deprecated path\n\n**Contract:** Do not delete skills during exploratory surgery. Redirect first; deletion requires explicit operator approval after review.\n\n资料来源：[skills/skill-surgery-rd/SKILL.md:67-73]()\n\n## Artifact Routing\n\nSkills generate artifacts that follow a consistent routing pattern:\n\n| Artifact Type | Path Pattern | Purpose |\n|---------------|--------------|---------|\n| New skill | `~/.agents/skills/<slug>/SKILL.md` | Reusable capability |\n| Updated skill | Same path as existing skill | Extended capability |\n| Crystallization log | `docs/plans/crystallization-log.md` | History of all crystallizations |\n| Reports | `ShadowArchive/80-reports/` | Session summaries |\n| Tool signals | `tools/integrate/tool-signals.jsonl` | Per-fix results |\n\n资料来源：[skills/crystallize/SKILL.md:80-91]()\n\n## Integration with Agent Memory\n\nSkills can be integrated with persistent memory systems:\n\n### Memory Kinds\n\n| Kind | Purpose | Example |\n|------|---------|---------|\n| `fact` | Permanent facts | \"TypeScript is the primary language\" |\n| `commitment` | Future tasks | \"Need to finish setup by Friday\" |\n| `decision` | Choices made | \"Decided to use local-first\" |\n| `preference` | User preferences | User prefers dark mode |\n| `context` | Session context | Current project state |\n\n### Memory Extraction Pipeline\n\nSkills can trigger memory extraction through the `qmd-memory` interface:\n\n```bash\n# Extract from text\nqmd-memory extract notes.md --source-id \"file:notes.md\"\n\n# From piped data\nbee conversations get <id> --json | jq -r '.summary' | qmd-memory extract - --source-id \"bee:conv:<id>\"\n```\n\n资料来源：[skills/qmd-memory/SKILL.md:1-35]()\n\n## Multi-Model Skill Distribution\n\nSkills can delegate execution to specialized models based on task requirements:\n\n```mermaid\ngraph LR\n    A[Intent] --> B{Route Decision}\n    B -->|Code| C[Codex]\n    B -->|Research| D[Gemini]\n    B -->|Local| E[Ollama]\n    B -->|Synthesis| F[Multi-Model]\n    C --> G[Execute]\n    D --> G\n    E --> G\n    F --> G\n```\n\n### Provider-Specific Preparation\n\nBefore delegating, apply model-specific transforms:\n\n| Provider | Transform |\n|----------|-----------|\n| `qwen3` (any Ollama model) | Prepend `/no_think` to prompt or set `options.think = false` |\n| `codex` (mcp) | Use `mcp__codex__codex` tool with workdir set to current project |\n| `gemini` (openrouter) | Use `google/gemini-2.0-flash-001` for speed, `google/gemini-2.5-pro` for depth |\n| `Codex` (ACP anthropic) | Use `Codex-sonnet-4-6` default, `Codex-opus-4-6` for complex tasks |\n\n## Fallback Chain Pattern\n\nRobust skills implement a fallback chain for resilience:\n\n```\n1. Primary: Full scan/operation\n2. Degraded: Local paths only\n3. Offline: Skip unreachable, continue with available\n4. API unavailable: Report; proceed with manual or cached\n5. Empty: Report; note likely path issue\n6. Last resort: Minimal coverage with explicit statement of degradation\n```\n\nEach failure mode should have a documented recovery action that allows the skill to continue or gracefully report inability.\n\n## Relationship to Agent Infrastructure\n\n### Skill Discovery Order\n\nFor context-based skills, the read order defines precedence:\n\n1. `/Volumes/☯Duality/AGENTS.md` — master control surface\n2. `reference/SHADOW-CONTEXT.md` — quick paths and fleet\n3. `reference/ARCHITECTURE.md` — layered architecture\n4. `reference/SHADOW-ARCHITECTURE-SPEC.md` — full spec\n5. `reference/VERIFIABILITY.md` — proof-of-work rules\n6. `docs/reference/SHADOW-DUALITY-ORGANIZATION.md` — rings + artifact resolution\n\n### Skills Namespace\n\nAll skills feed into the same namespace regardless of origin:\n\n- **First-party:** `/Volumes/☯Duality/skills/`\n- **Vendor:** `/Volumes/☯Duality/.agents/skills/`\n- **Project-specific:** `.agents/skills/`\n- **Enterprise:** Appropriate subdirectory under `~/.agents/skills/`\n\nThis unified namespace allows agents to discover and invoke any skill regardless of its origin point.\n\n## Best Practices Summary\n\n1. **Trigger Clarity:** Always include \"Use when...\" clause with specific trigger phrases\n2. **Size Discipline:** Keep SKILL.md under 100 lines; extract to REFERENCE.md for extended content\n3. **Deterministic Scripts:** Use utility scripts for repetitive, predictable operations\n4. **Crystallization Logging:** Record session date, context, and pattern extracted\n5. **No Stale Data:** Avoid version numbers, pricing, or API shapes that will become outdated\n6. **Preserve History:** Never delete skills; redirect deprecated ones\n7. **Single Responsibility:** One skill = one capability; split when domains diverge\n8. **Citation:** Reference source patterns when extracting from other skills\n\n---\n\n<a id='skill-dependencies'></a>\n\n## Skill Dependencies & Metadata\n\n### 相关页面\n\n相关主题：[Skill Structure & Anatomy](#skill-structure), [Crystallize - Pattern Extraction](#crystallize)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n- [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n- [skills/shadow-engg/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-engg/SKILL.md)\n- [skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)\n- [skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n- [skills/qmd-memory/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/qmd-memory/SKILL.md)\n- [skills/shadow-mcp-gadgets/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mcp-gadgets/SKILL.md)\n</details>\n\n# Skill Dependencies & Metadata\n\n## Overview\n\nThe s4b7-ai-skills repository implements a structured approach to skill documentation that encompasses metadata standards, dependency management, and artifact routing. Each skill follows a consistent SKILL.md template that defines its purpose, trigger conditions, workflows, and integration points with other system components.\n\nThe metadata system serves three core purposes: enabling agent-based skill selection through descriptive frontmatter, establishing clear execution workflows with fallback chains, and routing artifacts to appropriate storage locations for persistence and retrieval.\n\n## Skill Metadata Structure\n\n### Frontmatter Schema\n\nEvery skill in the repository begins with YAML frontmatter that defines its identity and selection criteria. The required metadata fields ensure proper agent routing and discovery.\n\n| Field | Purpose | Constraints |\n|-------|---------|-------------|\n| `name` | Skill identifier | Unique within skill namespace |\n| `description` | Capability summary for agent selection | Max 1024 chars, third person, must include \"Use when...\" clause |\n| `triggers` | Keywords and contexts that activate the skill | Extracted from description for matching |\n\n资料来源：[skills/write-a-skill/SKILL.md:1-20]()\n\n### Description Requirements\n\nThe description field is the primary mechanism by which agents decide which skill to load. It must follow a strict two-sentence format:\n\n1. **First sentence**: States what the skill does\n2. **Second sentence**: Contains the \"Use when...\" clause specifying trigger conditions\n\nExample of a well-formed description:\n\n```\nExtract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.\n```\n\n资料来源：[skills/write-a-skill/SKILL.md:52-56]()\n\nThe description is surfaced in the system prompt alongside all other installed skills, allowing the agent to pick the relevant skill based on the user's request. This makes the description the single most important metadata element for skill discoverability.\n\n### Skill Kinds and Tags\n\nThe `qmd-memory` skill implements a tagging system for memory classification that can be applied to skill metadata:\n\n| Kind | Usage |\n|------|-------|\n| `fact` | Permanent factual information |\n| `commitment` | Promises or obligations |\n| `decision` | Choices made during execution |\n| `preference` | User or system preferences |\n| `context` | Session-specific context |\n\nTags provide additional dimension to skill metadata, enabling filtering and targeted recall.\n\n资料来源：[skills/qmd-memory/SKILL.md:45-52]()\n\n## Skill Modes and Command Routing\n\n### Mode Architecture\n\nSkills expose multiple operational modes that define different execution paths. The mode system allows a single skill to handle diverse use cases through command-based routing.\n\n```mermaid\ngraph TD\n    A[User Input] --> B{Mode Detection}\n    B -->|default| C[Standard Execution]\n    B -->|verbose| D[Detailed Diagnostics]\n    B -->|json| E[Machine Output]\n    B -->|background| F[Autonomous Loop]\n    \n    C --> G[Primary Handler]\n    D --> H[Debug Handler]\n    E --> I[Parse Handler]\n    F --> J[Background Agent]\n    \n    G --> K[Result Output]\n    H --> K\n    I --> K\n    J --> K\n```\n\n资料来源：[skills/codex-latex/SKILL.md:35-48]()\n\n### Mode Reference by Skill\n\n| Skill | Modes | Purpose |\n|-------|-------|---------|\n| `ai-sdk-core` | migrate, agent, error, workers, verify | AI SDK v5/v6 lifecycle management |\n| `shadow-engg` | explore, engineering | Competitive intelligence and gap analysis |\n| `shadow-refactor` | background, patterns, hotspot, equilibrium | Code refactoring and pattern extraction |\n| `shadow-mcp-gadgets` | memory, context, mesh, browser, ambient, voice, environment, patent, test | MCP tool delegation |\n\n资料来源：[skills/shadow-engg/SKILL.md:1-30](), [skills/shadow-refactor/SKILL.md:1-15](), [skills/shadow-mcp-gadgets/SKILL.md:1-20]()\n\n## Artifact Routing System\n\n### Artifact Types\n\nArtifacts are outputs produced during skill execution that require persistent storage. Each skill defines a routing table specifying where artifacts should be stored.\n\n| Artifact Type | Path Pattern | Purpose |\n|--------------|--------------|---------|\n| Tool signals | `tools/integrate/tool-signals.jsonl` | Per-fix results in JSONL format |\n| Refactor reports | `ShadowArchive/80-reports/refactor-<target>-YYYY-MM-DD.md` | Session summaries |\n| Memory stores | `ARC memory store` | Persistent agent memory |\n| Patent drafts | `docs/patents/SP-NNN/` | Specification and claims |\n\n资料来源：[skills/shadow-refactor/SKILL.md:15-22](), [skills/shadow-mcp-gadgets/SKILL.md:22-28]()\n\n### Artifact Routing Table Format\n\nSkills implement artifact routing through structured tables in SKILL.md:\n\n```\n| Artifact | Location | Purpose |\n|----------|----------|---------|\n| Code changes | Project files (inline) | Implementation output |\n| Detailed reference | `REFERENCE.md` (skill companion) | Migrations, errors, model notes |\n| Original backup | `data/skill-rd/active-split-backups/` | Pre-split archive |\n```\n\n资料来源：[skills/ai-sdk-core/SKILL.md:28-33]()\n\n## Fallback Chain Architecture\n\n### Fallback Principles\n\nEvery skill implements a fallback chain that defines recovery behavior when primary execution paths fail. The chain prioritizes available alternatives in order of preference.\n\n```mermaid\ngraph LR\n    A[Primary] --> B[Secondary]\n    B --> C[Tertiary]\n    C --> D[Last Resort]\n    \n    style A fill:#90EE90\n    style B fill:#FFE4B5\n    style C fill:#FFA07A\n    style D fill:#FF6B6B\n```\n\n### Fallback Chain Examples\n\n**ai-sdk-core Fallback Chain:**\n\n| Priority | Source | Condition |\n|----------|--------|-----------|\n| 1 | `REFERENCE.md` | Detailed reference available |\n| 2 | Web search / docs | REFERENCE.md stale or missing |\n| 3 | `npm view ai versions` | Version uncertainty |\n| 4 | Stable v5 default | All else fails |\n\n资料来源：[skills/ai-sdk-core/SKILL.md:35-42]()\n\n**shadow-engg Fallback Chain:**\n\n| Priority | Mode | Condition |\n|----------|------|-----------|\n| 1 | Full scan | ShadowArchive mounted, skills accessible |\n| 2 | Local-only | Archive unmounted |\n| 3 | Skip mesh health | Tailscale mesh unreachable |\n| 4 | Report API status | Caresoft API unavailable |\n\n资料来源：[skills/shadow-engg/SKILL.md:55-68]()\n\n**skill-surgery-rd Error Handling:**\n\n| Failure | Recovery |\n|---------|----------|\n| Script execution fails | Manual `find + grep` inventory |\n| Malformed YAML frontmatter | Flag; propose manual repair |\n| Circular redirect detected | Block; require manual resolution |\n| Too many skills (>500) | Prioritize active; sample archived |\n\n资料来源：[skills/skill-surgery-rd/SKILL.md:45-55]()\n\n## Skill Dependencies and Interconnections\n\n### Crystallization Workflow\n\nThe crystallization process creates dependencies between skills by extracting patterns from working sessions into reusable skill definitions.\n\n```mermaid\ngraph TD\n    A[Task Complete] --> B{Should this recur?}\n    B -->|yes| C[Review Session]\n    B -->|no| D[Done]\n    C --> E[Extract Pattern]\n    E --> F[Check Scope]\n    F --> G{Search Existing Skills}\n    G -->|overlap found| H[Update Existing]\n    G -->|no overlap| I[Create New Skill]\n    H --> J[Log Crystallization]\n    I --> J\n```\n\n资料来源：[skills/crystallize/SKILL.md:55-78]()\n\n### Exploratory-Mode Expansion\n\nWhen operators request expanded crystallization, the skill performs a broader sweep:\n\n1. Start from the exact thing that was fixed\n2. Check nearest adjacent surfaces that could carry the same stale assumption\n3. Capture the broader reusable rule\n\n资料来源：[skills/crystallize/SKILL.md:75-85]()\n\n### Skill Surgery and Dependencies\n\nThe `skill-surgery-rd` skill manages skill dependencies through audit and repair operations. Key operations include:\n\n- **Audit**: Scan skill directories for stale metadata, circular dependencies, or missing trigger conditions\n- **Merge**: Combine overlapping skills while preserving gotchas from both sources\n- **Redirect**: Route deprecated skill triggers to canonical replacements\n\n资料来源：[skills/skill-surgery-rd/SKILL.md:1-45]()\n\n## File Reference System\n\n### Global File Registry\n\nThe `codex-context` skill maintains a master file reference table for system-wide file access:\n\n| File | Purpose | Location |\n|------|---------|----------|\n| Codex config | Model, sandbox, MCP, plugins | `~/.codex/config.toml` |\n| Codex memories | Persistent memory across sessions | `~/.codex/memories/MEMORY.md` |\n| Codex rules | Caveman mode rules | `~/.codex/rules/*.md` |\n| Codex prompts | Will, swarm, review, skill-up | `~/.codex/prompts/*.md` |\n| Hermes SOUL.md | Shadow persona (default) | `~/.hermes/SOUL.md` |\n| Gemini GEMINI.md | YOLO mode + global rules | `~/.gemini/GEMINI.md` |\n\n资料来源：[skills/codex-context/SKILL.md:85-98]()\n\n### Key Path Resolution\n\n| Path Type | Location |\n|-----------|----------|\n| ShadowArchive | `/Volumes/☯Duality/ShadowArchive/` |\n| Reports | `ShadowArchive/80-reports/` |\n| Agent roots | `ShadowArchive/03-agent-roots/` |\n| Registry | `ShadowArchive/01-registry/` |\n| First-party skills | `/Volumes/☯Duality/skills/` |\n| Vendor skills | `/Volumes/☯Duality/.agents/skills/` |\n\n资料来源：[skills/codex-context/SKILL.md:35-48]()\n\n## Contract and Constraints\n\n### Skill Contracts\n\nEach skill defines a contract specifying operational boundaries:\n\n| Contract Element | Description |\n|-----------------|-------------|\n| Context persistence | Do not persist without operator request |\n| Zone boundaries | Enterprise context does not leak into personal zone |\n| Recall confidence | Always label confidence level |\n| Memory writes | Append-only, never destructive |\n\n资料来源：[skills/shadow-mind/SKILL.md:75-85]()\n\n### Operational Rules\n\n**skill-surgery-rd Contract:**\n\n- Do not delete skills during exploratory surgery — redirect first\n- Do not edit archived history unless surfacing as active trigger problem\n- Do not create giant omnibus skills — prefer canonical router plus focused subskills\n- Research before invention — never crystallize stale version numbers without freshness note\n\n资料来源：[skills/skill-surgery-rd/SKILL.md:57-70]()\n\n**shadow-engg Contract:**\n\n- Never modify production config without operator confirmation\n- Report all changes with before/after diff\n- Preserve existing configurations with backup\n\n资料来源：[skills/shadow-engg/SKILL.md:125-130]()\n\n## Integration with MCP Gadgets\n\n### Gadget Mode Routing\n\nThe `shadow-mcp-gadgets` skill routes commands to specialized tools based on trigger phrases:\n\n| Mode | Gadget | Triggers |\n|------|--------|----------|\n| `memory` | ARC | `arc.store`, `arc.search`, memory triggers |\n| `context` | ESP | `esp.assemble`, `/renew-ctx` |\n| `mesh` | ANT | `ant.mesh`, mesh health |\n| `browser` | TAP | `tap.tabs`, `tap.execute` |\n| `ambient` | OWL | `owl.brief`, `owl.extract` |\n| `voice` | ORB | `orb.say`, `orb.voices` |\n| `environment` | DEN | `den.environment` |\n| `patent` | Factory | `factory.new`, `factory.draft` |\n\n资料来源：[skills/shadow-mcp-gadgets/SKILL.md:8-18]()\n\n## Recall Scoring System\n\nThe `shadow-mind` skill implements confidence-based recall for skill metadata:\n\n| Confidence Level | Meaning | Source |\n|-----------------|---------|--------|\n| **Confirmed** | Found in durable artifact (anchor, kernel, Dropbox) | File match |\n| **Likely** | Found in training pairs or distilled experience | Pattern match |\n| **Inferred** | Reconstructed from context but no explicit artifact | Reasoning |\n| **Unknown** | No evidence found | No match |\n\nAlways label recall confidence. Never present inferred as confirmed.\n\n资料来源：[skills/shadow-mind/SKILL.md:55-65]()\n\n## Review Checklist\n\nAfter drafting or updating skill metadata, verify:\n\n- [ ] Description includes \"Use when...\" trigger clause\n- [ ] SKILL.md under 100 lines (split if exceeded)\n- [ ] No time-sensitive info that will become stale\n- [ ] Consistent terminology with adjacent skills\n- [ ] Concrete examples included\n- [ ] References one level deep only\n\n资料来源：[skills/write-a-skill/SKILL.md:95-102]()\n\n---\n\n<a id='langgraph-agent'></a>\n\n## LangGraph Agent Development\n\n### 相关页面\n\n相关主题：[AI SDK Core - Vercel Integration](#ai-sdk-core), [Agent Crystallization Protocol](#agent-cryst)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/langgraph-agent/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/langgraph-agent/SKILL.md)\n- [skills/langgraph-agent/references/advanced-patterns.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/langgraph-agent/references/advanced-patterns.md)\n\n**Note:** The specified source files were referenced in the query but were not included in the retrieved context. This wiki page is generated using standard LangGraph patterns and conventions consistent with the repository's skill documentation style.\n\n</details>\n\n# LangGraph Agent Development\n\n## Overview\n\nLangGraph Agent Development provides a framework for building stateful, multi-agent applications using LangGraph's graph-based architecture. It enables developers to create agents that maintain context across interactions, coordinate multiple sub-agents, and handle complex workflow orchestration through explicit state management and conditional routing.\n\nLangGraph extends the concept of LLM chains by introducing nodes (agents/tools) and edges (transitions) within a directed graph structure, allowing for more sophisticated agentic behaviors than linear chain implementations.\n\n## Core Concepts\n\n### Graph Architecture\n\nLangGraph applications are built as stateful graphs composed of nodes and edges:\n\n| Component | Description | Role in Architecture |\n|-----------|-------------|---------------------|\n| **State** | Shared data structure passed between nodes | Centralized memory model |\n| **Nodes** | Functions representing agents or tools | Execute tasks, modify state |\n| **Edges** | Define transitions between nodes | Control flow logic |\n| **Conditional Edges** | Dynamic routing based on state | Decision-making paths |\n\n### State Management\n\nState in LangGraph is typically a TypedDict or Pydantic model that accumulates data as it flows through the graph:\n\n```python\nfrom typing import TypedDict\nfrom typing_extensions import Annotated\nimport operator\n\nclass AgentState(TypedDict):\n    messages: Annotated[list, operator.add]\n    context: dict\n    next_action: str\n```\n\nThe `Annotated` type with `operator.add` enables message accumulation, where each node appends to the messages list rather than replacing it.\n\n## Workflow Patterns\n\n### Basic Agent Loop\n\n```mermaid\ngraph TD\n    A[User Input] --> B[LLM Decision Node]\n    B --> C{Should Respond?}\n    C -->|Yes| D[Return to User]\n    C -->|No| E{Should Use Tool?}\n    E -->|Yes| F[Execute Tool]\n    E -->|No| G[Continue to Next Node]\n    F --> H[Update State]\n    H --> B\n    G --> I[End or Next Agent]\n    I --> D\n```\n\n### Multi-Agent Orchestration\n\nFor complex tasks, LangGraph enables hierarchical agent architectures:\n\n| Pattern | Use Case | Description |\n|---------|----------|-------------|\n| **Supervisor** | Single task delegation | One agent routes to specialized sub-agents |\n| **Hierarchical** | Complex workflows | Multiple supervisor levels manage complexity |\n| **Collaborative** | Parallel processing | Agents share context and contribute to solution |\n\n## Advanced Patterns\n\n### Human-in-the-Loop\n\nIntegrating human feedback into agent execution:\n\n```python\ndef human_review_node(state: AgentState) -> AgentState:\n    user_input = interrupt(\"Awaiting human review...\")\n    return {\"feedback\": user_input}\n```\n\nThe `interrupt` function pauses execution and yields control to external systems (UIs, APIs) for human approval before resuming.\n\n### Memory Persistence\n\nLangGraph supports checkpointing for long-running conversations:\n\n```python\nfrom langgraph.checkpoint.sqlite import SqliteSaver\n\ncheckpointer = SqliteSaver.from_conn_string(\":memory:\")\ngraph = compileprompt | model | parser, checkpointer=checkpointer)\n```\n\nCheckpoints enable:\n- Conversation resumption after interruptions\n- Branching for exploration\n- Audit trails of agent decisions\n\n### Tool Integration\n\nTools are defined as functions and integrated into the graph:\n\n```python\nfrom langchain_core.tools import tool\n\n@tool\ndef search_codebase(query: str) -> str:\n    \"\"\"Search the codebase for relevant files.\"\"\"\n    # Implementation\n    return results\n\ntools = [search_codebase]\n```\n\n## API Reference\n\n### Compiling the Graph\n\n```python\nfrom langgraph.graph import StateGraph, END\n\nworkflow = StateGraph(AgentState)\nworkflow.add_node(\"agent\", agent_node)\nworkflow.add_node(\"tools\", tool_node)\n\nworkflow.set_entry_point(\"agent\")\nworkflow.add_conditional_edges(\n    \"agent\",\n    should_continue,\n    {\n        \"continue\": \"agent\",\n        \"end\": END,\n    }\n)\n\napp = workflow.compile()\n```\n\n### Key Parameters\n\n| Parameter | Type | Purpose |\n|-----------|------|---------|\n| `checkpointer` | BaseCheckpointSaver | Enables state persistence |\n| `interrupts` | list | Pause points for external input |\n| `debug` | bool | Enable verbose execution logging |\n\n## Best Practices\n\n### Error Handling\n\nImplement retry logic and fallbacks within nodes:\n\n```python\ndef robust_agent_node(state: AgentState) -> AgentState:\n    max_retries = 3\n    for attempt in range(max_retries):\n        try:\n            result = risky_operation(state)\n            return {\"result\": result, \"status\": \"success\"}\n        except Exception as e:\n            if attempt == max_retries - 1:\n                return {\"error\": str(e), \"status\": \"failed\"}\n            continue\n```\n\n### State Optimization\n\nMinimize state size to improve performance:\n\n- Use references (IDs) instead of full objects where possible\n- Implement state pruning at node boundaries\n- Separate ephemeral vs. persistent state concerns\n\n### Testing Strategies\n\n| Approach | Target | Method |\n|----------|--------|--------|\n| Unit tests | Individual nodes | Mock state input/output |\n| Integration tests | Full graph paths | Use deterministic checkpointer |\n| Property-based tests | State transitions | Verify invariants across runs |\n\n## Integration with s4b7-ai-skills\n\nThe LangGraph Agent Development skill follows the repository's skill template structure:\n\n- **Quick Start**: Minimal working example for agent initialization\n- **Workflows**: Step-by-step processes with checklists\n- **Advanced Features**: Referenced in companion files for specialized patterns\n\n资料来源：[skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n\n## Related Skills\n\n| Skill | Purpose |\n|-------|---------|\n| `shadow-refactor` | Code refactoring patterns for agent implementations |\n| `crystallize` | Extract reusable patterns from agent sessions |\n| `ai-sdk-core` | V5/V6 migration guidance for AI SDK integration |\n\n## Conclusion\n\nLangGraph Agent Development provides the architectural foundation for building sophisticated, stateful agent systems. By modeling agents as nodes in a graph with explicit state management and conditional routing, developers can create predictable, debuggable, and scalable agentic applications that handle complex multi-step workflows effectively.\n\n---\n\n<a id='ai-sdk-core'></a>\n\n## AI SDK Core - Vercel Integration\n\n### 相关页面\n\n相关主题：[LangGraph Agent Development](#langgraph-agent)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n- [skills/ai-sdk-core/references/v5-breaking-changes.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/v5-breaking-changes.md)\n- [skills/ai-sdk-core/references/top-errors.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/top-errors.md)\n- [skills/ai-sdk-core/references/providers-quickstart.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/providers-quickstart.md)\n- [skills/ai-sdk-core/references/links-to-official-docs.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/links-to-official-docs.md)\n</details>\n\n# AI SDK Core - Vercel Integration\n\n## Overview\n\nThe AI SDK Core skill provides a comprehensive toolkit for building backend AI applications using the Vercel AI SDK. It supports both stable v5 and v6 beta releases, offering capabilities for text generation, streaming, structured output, and agent-based workflows.\n\nThis skill targets developers implementing AI-powered backend routes, migrating between SDK versions, troubleshooting runtime errors, or integrating with latest AI models from OpenAI, Anthropic, and Google.\n\n**资料来源：** [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n\n## Skill Metadata\n\n| Property | Value |\n|----------|-------|\n| **Name** | AI SDK Core |\n| **Version** | 1.2.0 |\n| **Last Verified** | 2025-11-22 |\n| **Stable SDK Version** | 5.0.98 |\n| **Beta SDK Version** | 6.0.0-beta.107 |\n| **Production Tested** | Yes |\n| **License** | MIT |\n| **Dependencies** | ai-fi-manager |\n\n**资料来源：** [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n\n## Supported Capabilities\n\n### Core Functions\n\n| Function | Purpose |\n|----------|---------|\n| `generateText` | Non-streaming text generation |\n| `streamText` | Streaming text generation with real-time output |\n| `generateObject` | Structured output generation with Zod schema validation |\n| `streamObject` | Streaming structured object generation |\n\n### Advanced Features (v6 Beta)\n\n| Feature | Description |\n|---------|-------------|\n| **Agent Abstraction** | Built-in agent class with tool support |\n| **Tool Approval** | Human-in-the-loop approval workflow |\n| **Reranking Support** | Semantic search reranking capabilities |\n\n**资料来源：** [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n\n## Quick Start Workflow\n\n```mermaid\ngraph TD\n    A[Task Request] --> B{Identify Task Type}\n    B -->|New Route| C[Core Functions]\n    B -->|Agent/Tool Loop| D[v6 Agent Abstraction]\n    B -->|Migration| E[Breaking Change Checklist]\n    B -->|Error Fix| F[Error Cookbook]\n    C --> G[Install Packages]\n    D --> G\n    E --> H[Follow Migration Guide]\n    F --> I[Apply Recipe]\n    G --> J[Implement & Test]\n    H --> J\n    I --> J\n```\n\n### Installation\n\n```bash\nnpm install ai @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google zod\n\n# Beta lane when explicitly needed:\nnpm install ai@beta @ai-sdk/openai@beta @ai-sdk/react@beta\n```\n\n**资料来源：** [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n\n### Task Routing\n\n| Task | Starting Point |\n|------|----------------|\n| New backend AI route | Core functions: `generateText`, `streamText`, `generateObject`, `streamObject` |\n| Agent/tool loop | v6 Agent abstraction in `REFERENCE.md` |\n| v4→v5 migration | Breaking-change checklist in `REFERENCE.md` |\n| Cloudflare Worker startup | Lazy-import Workers fix in `REFERENCE.md` |\n| Runtime error | Error cookbook in `REFERENCE.md` |\n| Current model selection | Verify provider docs, then use provider examples in `REFERENCE.md` |\n\n**资料来源：** [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n\n## v4 to v5 Breaking Changes\n\nThe migration from v4 to v5 introduces several breaking changes that require code updates.\n\n**资料来源：** [skills/ai-sdk-core/references/v5-breaking-changes.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/v5-breaking-changes.md)\n\n### Message Types Renaming\n\n| v4 Type | v5 Type | Purpose |\n|---------|---------|---------|\n| `CoreMessage` | `ModelMessage` | Messages for the model |\n| `Message` | `UIMessage` | UI hooks |\n| `convertToCoreMessages` | `convertToModelMessages` | Conversion utility |\n\n**Before (v4):**\n```typescript\nimport { CoreMessage, convertToCoreMessages } from 'ai';\n\nconst messages: CoreMessage[] = [\n  { role: 'user', content: 'Hello' },\n];\n\nconst converted = convertToCoreMessages(uiMessages);\n```\n\n**After (v5):**\n```typescript\nimport { ModelMessage, convertToModelMessages } from 'ai';\n\nconst messages: ModelMessage[] = [\n  { role: 'user', content: 'Hello' },\n];\n\nconst converted = convertToModelMessages(uiMessages);\n```\n\n**资料来源：** [skills/ai-sdk-core/references/v5-breaking-changes.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/v5-breaking-changes.md)\n\n### Tool Error Handling\n\n| Aspect | v4 Behavior | v5 Behavior |\n|--------|-------------|-------------|\n| Error Type | `ToolExecutionError` | Regular `Error` |\n| Error Location | Thrown explicitly | Appears as content parts |\n| Execution Impact | Stops execution | Continues with error in stream |\n\n**Before (v4):**\n```typescript\nimport { ToolExecutionError } from 'ai';\n\nconst tools = {\n  risky: {\n    execute: async (args) => {\n      throw new ToolExecutionError({\n        message: 'API failed',\n        cause: originalError,\n      });\n    },\n  },\n};\n```\n\n**After (v5):**\n```typescript\nconst tools = {\n  risky: tool({\n    execute: async (input) => {\n      throw new Error('API failed');\n    },\n  }),\n};\n```\n\n**资料来源：** [skills/ai-sdk-core/references/v5-breaking-changes.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/v5-breaking-changes.md)\n\n## Error Solutions\n\nThe skill includes a cookbook with 12+ error solutions covering common runtime issues.\n\n| Error Category | Count | Coverage |\n|----------------|-------|----------|\n| `AI_APICallError` | 1+ | API communication failures |\n| `AI_NoObjectGeneratedError` | 1+ | Structured output failures |\n| Stream Text Silent Errors | 1+ | Stream consumption issues |\n| Cloudflare Workers Errors | 1+ | Worker-specific problems |\n\n**资料来源：** [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n\n### Common Decision Points\n\n| Scenario | Recommendation |\n|----------|-----------------|\n| Stable vs Beta | Prefer stable v5 unless v6 beta features explicitly requested |\n| Workers startup | Use lazy imports when startup budget matters |\n| Stream errors | Treat `streamText` silent failures as error-handling problem, not only provider problem |\n| Model IDs/Prices | Do not hard-code; verify first before use |\n\n**资料来源：** [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n\n## Provider Integration\n\n### Supported Providers\n\n| Provider | Package | Models |\n|----------|---------|--------|\n| OpenAI | `@ai-sdk/openai` | GPT-5, GPT-5.1 |\n| Anthropic | `@ai-sdk/anthropic` | Claude 4.x series |\n| Google | `@ai-sdk/google` | Gemini 2.5 |\n\n**资料来源：** [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n\n### Cloudflare Workers Special Handling\n\nCloudflare Workers have strict startup budgets. When implementing AI SDK in Workers environments:\n\n1. Use lazy imports for AI SDK packages\n2. Defer model initialization until first request\n3. Apply the Workers-specific fix from `REFERENCE.md`\n\n**资料来源：** [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n\n## Fallback Chain\n\nWhen primary references are unavailable or stale, use this fallback sequence:\n\n```mermaid\ngraph LR\n    A[Request] --> B{REFERENCE.md Available?}\n    B -->|Yes| C[Use Detailed Reference]\n    B -->|No| D{Web Search Available?}\n    D -->|Yes| E[Search Official Docs]\n    D -->|No| F{npm view Available?}\n    F -->|Yes| G[Check Latest Version]\n    F -->|No| H[Use Stable v5 Default]\n```\n\n| Priority | Source | Use Case |\n|----------|--------|----------|\n| 1 | `REFERENCE.md` detailed reference | Migrations, errors, model notes |\n| 2 | Web search / docs | Stale or missing version info |\n| 3 | `npm view ai versions` | Version uncertainty |\n| 4 | Stable v5 default | Last resort |\n\n**资料来源：** [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n\n## Artifact Routing\n\n| Artifact | Location | Purpose |\n|----------|----------|---------|\n| Code changes | Project files (inline) | Implementation output |\n| Detailed reference | `REFERENCE.md` (skill companion) | Migrations, errors, model notes |\n| Original backup | `data/skill-rd/active-split-backups/2026-05-02/ai-sdk-core.SKILL.original.md` | Pre-split archive |\n\n**资料来源：** [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n\n## Reference File Structure\n\n```\nskills/ai-sdk-core/\n├── SKILL.md                          # Main skill file\n├── REFERENCE.md                      # Detailed reference\n├── references/\n│   ├── v5-breaking-changes.md       # v4→v5 migration guide\n│   ├── top-errors.md                 # Error cookbook\n│   ├── providers-quickstart.md       # Provider setup\n│   └── links-to-official-docs.md     # External resources\n├── templates/\n│   ├── generate-text-basic.ts\n│   ├── stream-text-chat.ts\n│   └── generate-object-zod.ts\n└── data/\n    └── skill-rd/\n        └── active-split-backups/     # Archive versions\n```\n\n**资料来源：** [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n\n## External Resources\n\n| Resource | URL |\n|----------|-----|\n| Official Documentation | https://ai-sdk.dev/ |\n| GitHub Repository | https://github.com/vercel/ai |\n| GitHub Issues | https://github.com/vercel/ai/issues |\n| GitHub Discussions | https://github.com/vercel/ai/discussions |\n| Discord Community | https://discord.gg/vercel |\n| AI SDK 5.0 Release Blog | https://vercel.com/blog/ai-sdk-5 |\n| Zod Documentation | https://zod.dev/ |\n\n**资料来源：** [skills/ai-sdk-core/references/links-to-official-docs.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/links-to-official-docs.md)\n\n## Complementary Skills\n\n| Skill | Purpose |\n|-------|---------|\n| **ai-sdk-ui** | Frontend React hooks (`useChat`, `useCompletion`, `useObject`) |\n| **cloudflare-workers-ai** | Native Cloudflare Workers AI binding (single-provider) |\n\n**资料来源：** [skills/ai-sdk-core/references/links-to-official-docs.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/links-to-official-docs.md)\n\n## Keywords\n\nThe skill is triggered by these terms:\n\n- ai sdk core, vercel ai sdk, ai sdk v5, ai sdk v6 beta, ai sdk 6\n- agent abstraction, tool approval, reranking support\n- human in the loop, generateText, streamText\n- generateObject, streamObject, ai sdk node, ai sdk server\n- zod ai schema, ai schema validation, ai tool calling\n- ai agent class, openai sdk, anthropic sdk\n\n**资料来源：** [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n\n---\n\n<a id='agent-cryst'></a>\n\n## Agent Crystallization Protocol\n\n### 相关页面\n\n相关主题：[Crystallize - Pattern Extraction](#crystallize), [Write A Skill - Authoring Guide](#write-a-skill)\n\n<details>\n<summary>Relevant Source Files</summary>\n\nThe following source files were used to generate this documentation:\n\n- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n- [skills/agent-cryst/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/agent-cryst/SKILL.md)\n- [skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n- [skills/shadow-mind/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mind/SKILL.md)\n- [README.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/README.md)\n</details>\n\n# Agent Crystallization Protocol\n\nThe Agent Crystallization Protocol is a systematic methodology for transforming implicit knowledge, problem-solving patterns, and learned insights from agent sessions into explicit, reusable, and discoverable skills. It serves as the intentional counterpart to automated pattern detection (SP-006), enabling agents to capture knowledge that emerges from reasoning and understanding rather than mere tool usage observation.\n\n## Purpose and Scope\n\nThe crystallization protocol addresses a fundamental challenge in agentic systems: knowledge decay and inability to reuse past solutions. When an agent successfully solves a complex problem, that solution remains trapped in session memory unless explicitly captured. The crystallization protocol provides the workflow, standards, and tooling to extract these patterns into durable skills that future sessions can leverage.\n\n**Primary Objectives:**\n\n| Objective | Description |\n|-----------|-------------|\n| Knowledge Preservation | Convert session insights into persistent, reusable artifacts |\n| Pattern Formalization | Transform implicit heuristics into explicit, actionable workflows |\n| Skill Discoverability | Ensure crystallized knowledge is findable and loadable by agents |\n| Quality Assurance | Maintain skill standards through validation and documentation requirements |\n| Organizational Learning | Enable cross-session and cross-domain knowledge transfer |\n\n**Scope Boundaries:**\n\nThe protocol distinguishes between what should be crystallized and what should not:\n\n- **Crystallize:** Novel problem-solving approaches, reusable workflows, decision heuristics, gotchas discovered through reasoning, cross-domain patterns\n- **Do Not Crystallize:** Time-sensitive information (pricing, API versions), obvious operations derivable from codebase inspection, highly specific one-off solutions 资料来源：[skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n## Architecture Overview\n\nThe crystallization system operates as a closed loop between session execution and skill repository management:\n\n```mermaid\ngraph TD\n    A[Agent Session] -->|Completes Task| B{Should this recur?}\n    B -->|Yes| C[Review Session]\n    B -->|No| Z[Session Ends]\n    C --> D[Extract Pattern]\n    D --> E[Check Scope]\n    E --> F{Skill overlap found?}\n    F -->|Yes| G[Update Existing Skill]\n    F -->|No| H[Create New Skill]\n    G --> I[Log Crystallization Metadata]\n    H --> I\n    I --> J[Skill Repository]\n    J -->|Future Sessions| A\n```\n\n### Relationship to SP-006\n\nThe protocol intentionally complements SP-006 (Latent Skill Observer), which automatically detects patterns from tool call sequences:\n\n| Mechanism | Detection Method | Knowledge Type |\n|-----------|------------------|----------------|\n| SP-006 | Automated tool sequence analysis | Behavioral patterns from execution |\n| Crystallization Protocol | Intentional reasoning-based extraction | Conceptual patterns from understanding |\n\nBoth mechanisms feed into the same skill namespace, ensuring that automatically detected and intentionally crystallized knowledge coexist and reinforce each other. 资料来源：[skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n## Crystallization Workflow\n\nThe standard crystallization workflow proceeds through seven discrete phases:\n\n### Phase 1: Review Session\n\nBefore extracting any pattern, the agent must thoroughly understand what was accomplished:\n\n**Review Questions:**\n- What was the original task?\n- What problem was solved?\n- What was learned that wasn't known before?\n- What steps would be repeated identically in a similar future task?\n\nThis phase establishes the context necessary to determine whether crystallization is warranted and what form it should take. 资料来源：[skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n### Phase 2: Pattern Extraction\n\nThe core analytical phase where implicit knowledge becomes explicit. Extract four categories of information:\n\n**Key Steps:** The minimal sequence of actions that produces the desired result. Include only essential steps; omit accidental details from the specific session.\n\n**Heuristics:** The judgment calls required during execution. These are the \"rule of thumb\" decisions that determine success—where did the agent need to choose between approaches, and what guided that choice?\n\n**Gotchas:** What went wrong or nearly went wrong. Include assumptions that failed, edge cases that weren't anticipated, and common mistakes in the domain.\n\n**Decision Points:** Where the agent chose between competing approaches. Document both the choice made and the determining factors. 资料来源：[skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n### Phase 3: Exploratory Mode Expansion\n\nWhen the operator requests deeper crystallization or explicitly invokes `--exploratory-mode`, the protocol expands one \"ring\" outward from the immediate fix:\n\n```mermaid\ngraph LR\n    A[Exact Fix] --> B[Adjacent Surface 1]\n    A --> C[Adjacent Surface 2]\n    A --> D[Adjacent Surface 3]\n    B --> E{Same Stale Assumption?}\n    C --> E\n    D --> E\n    E -->|Yes| F[Capture Broader Pattern]\n    E -->|No| G[Leave Untouched]\n```\n\n**Exploratory Sweep Process:**\n1. Identify the exact element that was fixed\n2. Check the nearest adjacent surfaces that could carry the same stale assumption\n3. Evaluate whether the extracted pattern applies broadly or is specific to one surface\n4. Capture the broader reusable rule if the pattern holds across surfaces\n5. Explicitly note which adjacent surfaces were checked and intentionally left untouched 资料来源：[skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n### Phase 4: Scope Determination\n\nBefore creating or updating skills, determine the appropriate scope:\n\n| Scope | Location | Use Case |\n|-------|----------|----------|\n| General patterns | `~/.agents/skills/<skill-name>/SKILL.md` | Cross-domain, reusable anywhere |\n| Enterprise-specific | `~/.agents/skills/<enterprise>/` | Domain-scoped, team-specific |\n\nScope determination prevents the creation of skills that are either too narrow (duplicating existing capabilities) or too broad (mixing concerns that should be separate). 资料来源：[skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n### Phase 5: Deduplication Search\n\nBefore creating a new skill, search for existing skills that may overlap:\n\n**Search Targets:**\n- Skills with similar triggers or descriptions\n- Skills in adjacent domains that might subsume the new pattern\n- Deprecated skills that might redirect to canonical locations\n\n**Decision Matrix:**\n\n| Scenario | Action |\n|----------|--------|\n| Exact overlap found | Extend existing skill with new section |\n| Partial overlap found | Add to existing skill, avoid duplication |\n| Related but distinct | Create as separate skill, consider cross-reference |\n| No overlap found | Proceed with new skill creation |\n\nIf a related skill exists, add the new pattern as a new section or extend the existing workflow while preserving the skill's existing structure. 资料来源：[skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n### Phase 6: Skill Creation or Update\n\n#### Creating a New Skill\n\nFollow the standardized skill structure:\n\n```\n~/.agents/skills/<skill-name>/\n├── SKILL.md           # Primary skill definition\n├── REFERENCE.md       # Detailed reference (optional)\n└── scripts/           # Utility scripts (if needed)\n    └── helper.js\n```\n\n#### Updating an Existing Skill\n\nWhen extending an existing skill:\n1. Add new sections without modifying existing content structure\n2. Extend workflows only when the new pattern logically belongs\n3. Preserve all existing gotchas and decision points\n4. Update the \"Crystallized From\" metadata\n\n#### SKILL.md Template Structure\n\n```markdown\n---\nname: skill-name\ndescription: Brief description of capability. Use when [specific triggers].\n---\n\n# Skill Name\n\n## Quick start\n\n[Minimal working example]\n\n## Workflows\n\n[Step-by-step processes with checklists for complex tasks]\n\n## Advanced features\n\n[Link to separate files: See [REFERENCE.md](REFERENCE.md)]\n```\n\nThe `description` field is critical—it is the only information the agent sees when deciding which skill to load. It must include:\n- Maximum 1024 characters\n- Third-person perspective\n- First sentence: what the skill does\n- Second sentence: specific trigger conditions 资料来源：[skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n\n### Phase 7: Crystallization Logging\n\nRecord metadata at the bottom of the skill under `## Crystallized From`:\n\n```markdown\n## Crystallized From\n- Session: [date/context]\n- Original task: [what was being solved]\n- Pattern extracted: [what was captured]\n- Exploration mode: [what surfaces were checked]\n```\n\n**Optional:** Append to `docs/plans/crystallization-log.md` for historical tracking of all crystallizations. 资料来源：[skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n## Crystallization Modes\n\nThe protocol supports multiple modes to accommodate different urgency levels and depth requirements:\n\n| Mode | Output | Trigger Conditions |\n|------|--------|-------------------|\n| `default` | Full crystallization: review → extract → scope → deduplicate → create/update | `crystallize`, `capture this as a skill` |\n| `quick` | Fast capture to minimal skill stub; full refinement later | `quick crystallize`, mid-task pattern discovery |\n| `exploratory` | Expand one ring outward; check adjacent surfaces for same pattern | `--exploratory-mode`, `more crystallization` |\n| `drag-response` | Immediate crystallization from operator frustration | `this took too long`, `why aren't you using...` |\n| `correction` | Immediate update from operator correction | Operator corrects an identity/path/boundary |\n| `audit` | Check what should have been crystallized but wasn't | `what patterns did we miss` |\n\nThe mode determines the depth of analysis and the scope of expansion. Default mode provides thorough coverage; exploratory mode extends to adjacent surfaces; drag-response and correction modes prioritize speed for immediate pain points. 资料来源：[skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n## Artifact Routing\n\nAll crystallization outputs are routed to specific destinations based on their type:\n\n| Artifact Type | Destination | Purpose |\n|---------------|-------------|---------|\n| New skill | `~/.agents/skills/<slug>/SKILL.md` | Reusable capability |\n| Updated skill | Same path as existing skill | Extended capability |\n| Crystallization log | `docs/plans/crystallization-log.md` | Historical tracking (optional) |\n| Enterprise-specific skill | Appropriate `~/.agents/skills/<enterprise>/` subdirectory | Domain-scoped capability |\n\nSkill companions (detailed references, scripts) are co-located with their parent SKILL.md file. 资料来源：[skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n## Fallback Chain\n\nWhen primary resources are unavailable, the protocol follows a defined fallback chain:\n\n```\n1. Primary: Full workflow execution\n2. Fallback: Scan alternate skill paths\n3. Fallback: Skip unavailable services (Caresoft API, mesh nodes)\n4. Fallback: Report degraded state, continue with available data\n5. Last Resort: Minimal scan of current working directory only\n```\n\n| Failure | Recovery Action |\n|---------|----------------|\n| Primary skill directory not found | Check alternate paths; report; scan what's available |\n| ShadowArchive unmounted | Scan local paths only; note archive scan skipped |\n| Mesh unreachable | Skip mesh health checks; note offline nodes; continue |\n| Caresoft API unavailable | Report; skip engineering intelligence mode |\n| Skills directory empty | Report; likely path issue; suggest checking `~/.agents/skills/` |\n\nThe fallback chain ensures that crystallization can proceed at reduced fidelity rather than failing entirely when infrastructure components are unavailable. 资料来源：[skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n## Integration with Session Memory\n\nCrystallization does not operate in isolation—it integrates with broader session memory practices. After every session that produces decisions or discoveries:\n\n```mermaid\ngraph TD\n    A[Session Complete] --> B[Write Session Anchor]\n    B --> C[Append to ESP Context]\n    C --> D{Is this a reusable pattern?}\n    D -->|Yes| E[Crystallize to Skill]\n    D -->|No| F{Program-specific?}\n    F -->|Yes| G[Write to Session Log JSONL]\n    F -->|No| H[Discard or Archive]\n```\n\n**Session Anchor Storage:**\n- Write anchor to `ShadowArchive/80-reports/`\n- Append key decisions to `.shadow-kernel/esp-context.md` under topic heading\n- If pattern discovered → crystallize to skill\n- If program-specific → write to `<program>/90_Astemo_Config/session-log.jsonl` 资料来源：[skills/shadow-mind/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mind/SKILL.md)\n\n## Validation and Quality Standards\n\nCrystallized skills must meet minimum quality standards before being committed:\n\n### Review Checklist\n\n| Requirement | Standard |\n|-------------|----------|\n| Description | Includes trigger phrases (\"Use when...\") |\n| Length | SKILL.md under 100 lines |\n| Currency | No time-sensitive information without freshness notes |\n| Terminology | Consistent throughout the skill |\n| Examples | Concrete, working examples included |\n| References | Links to one level deep (e.g., REFERENCE.md, not REFERENCE.md#section |\n\n### Skill Validation\n\nWhen using skill validation tooling:\n- Ensure YAML frontmatter is properly formatted\n- Verify description character count under 1024\n- Confirm trigger phrases are present and specific\n- Check that workflows include actionable checklists 资料来源：[skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n\n## Contract and Boundaries\n\nThe crystallization protocol operates under explicit contracts that define acceptable behavior:\n\n| Contract Element | Requirement |\n|-----------------|--------------|\n| Context Scope | Context is session-scoped; do not persist without operator request |\n| Zone Boundaries | Respect zone boundaries; enterprise context does not leak into personal zone |\n| Recall Confidence | Always label recall confidence (Confirmed/Likely/Inferred/Unknown) |\n| Inference Presentation | Never present inferred recall as confirmed |\n| Memory Persistence | Memory writes are append-only, never destructive |\n| Skill Preservation | Do not delete skills during exploratory surgery; redirect first |\n| Omnibus Prevention | Do not create giant omnibus skills; prefer focused subskills with canonical router |\n| Externalization | All surgery reports go to ShadowArchive; no inline deletion |\n\nThese contracts ensure that crystallization enhances rather than compromises system integrity and operator trust. 资料来源：[skills/shadow-mind/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mind/SKILL.md)\n\n## Quick Reference\n\n### Triggering Crystallization\n\n```bash\n# Full crystallization\ncrystallize\n\n# Quick capture\nquick crystallize\n\n# Deep exploration\ncrystallize --exploratory-mode\n\n# Check for missed patterns\nwhat patterns did we miss\n```\n\n### Skill Discovery\n\n```bash\n# List available skills\nls ~/.agents/skills/\n\n# Search for specific capability\ngrep -r \"trigger phrase\" ~/.agents/skills/\n\n# Validate skill structure\nskill_validate <skill-path>\n```\n\n### Common Crystallization Patterns\n\n| Pattern Type | Best Practice |\n|--------------|---------------|\n| Novel workflow | Create dedicated skill with full template |\n| Extension to existing | Add new section, preserve existing structure |\n| Domain-specific | Create in appropriate enterprise subdirectory |\n| Cross-domain | Create in root, add cross-references |\n| Time-sensitive | Include freshness date and deprecation notice |\n\n## Related Documentation\n\n| Document | Purpose |\n|----------|---------|\n| [Agent Building Skills](../README.md#agent-building) | Overview of agent construction capabilities |\n| [write-a-skill](write-a-skill/SKILL.md) | Detailed skill authoring guide |\n| [skill-surgery-rd](skill-surgery-rd/SKILL.md) | Skill audit, repair, and gap analysis |\n| [shadow-mind](shadow-mind/SKILL.md) | Session memory and context management |\n\n---\n\n<a id='write-a-skill'></a>\n\n## Write A Skill - Authoring Guide\n\n### 相关页面\n\n相关主题：[Crystallize - Pattern Extraction](#crystallize), [Skill Surgery R&D](#skill-surgery-rd), [Skill Structure & Anatomy](#skill-structure)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n- [skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n- [skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)\n- [skills/codex-context/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-context/SKILL.md)\n</details>\n\n# Write A Skill - Authoring Guide\n\n## Overview\n\nThe **Write A Skill** authoring guide provides a standardized template and methodology for creating reusable agent capabilities within the skills ecosystem. Skills are self-contained units of functionality that agents can load and invoke based on context, enabling modular and maintainable agent behavior. 资料来源：[skills/write-a-skill/SKILL.md:1-15]()\n\nThis guide defines the canonical structure for skill development, including metadata requirements, workflow documentation patterns, and organizational best practices. The authoring framework ensures consistency across all skills while maintaining flexibility for diverse use cases.\n\n## Skill Anatomy\n\n### Core Components\n\nEvery skill follows a standardized directory structure to ensure predictability and discoverability:\n\n```\nskill-name/\n├── SKILL.md          # Primary documentation and entry point\n├── REFERENCE.md      # Advanced usage (optional)\n├── docs/             # Additional documentation (if needed)\n└── scripts/          # Utility scripts (if needed)\n    └── helper.js\n```\n\n资料来源：[skills/write-a-skill/SKILL.md:1-7]()\n\n### SKILL.md Template\n\nThe `SKILL.md` file serves as the primary interface for skill discovery and usage. It must follow this structure:\n\n```markdown\n---\nname: skill-name\ndescription: Brief description of capability. Use when [specific triggers].\n---\n\n# Skill Name\n\n## Quick start\n[Minimal working example]\n\n## Workflows\n[Step-by-step processes with checklists for complex tasks]\n\n## Advanced features\n[Link to separate files: See [REFERENCE.md](REFERENCE.md)]\n```\n\n资料来源：[skills/write-a-skill/SKILL.md:9-23]()\n\n## Metadata Requirements\n\n### Frontmatter Schema\n\nThe YAML frontmatter is **critical** for skill discovery. The agent system reads these fields to determine when to activate a skill.\n\n| Field | Type | Constraints | Purpose |\n|-------|------|-------------|---------|\n| `name` | string | lowercase, hyphenated | Unique identifier for the skill |\n| `description` | string | max 1024 chars, third person | Decision surface for skill selection |\n\n### Description Writing Guidelines\n\nThe description is **the only thing the agent sees** when deciding which skill to load. It appears in the system prompt alongside all other installed skills.\n\n**Required Format:**\n\n1. **First sentence**: What the capability provides\n2. **Second sentence**: Trigger conditions beginning with \"Use when...\"\n\n**Good Example:**\n```\nExtract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.\n```\n\n**Bad Examples:**\n```\nHelps with documents.\nPDF helper tool.\n```\n\n资料来源：[skills/write-a-skill/SKILL.md:33-48]()\n\nThe description must enable the agent to make an informed routing decision without additional context. Vague descriptions provide no discriminative value.\n\n## Content Organization\n\n### When to Add Scripts\n\nScripts should be introduced in specific scenarios:\n\n| Scenario | Rationale |\n|----------|-----------|\n| Operation is deterministic | Validation, formatting, or transformation logic that produces consistent results |\n| Same code would be generated repeatedly | DRY principle application; avoid token waste on regeneration |\n| Errors need explicit handling | Centralized error management with clear recovery paths |\n\nScripts save tokens and improve reliability compared to generated code. 资料来源：[skills/write-a-skill/SKILL.md:62-68]()\n\n### When to Split Files\n\nSplit into separate files when any of the following conditions are met:\n\n| Condition | Threshold | Rationale |\n|-----------|-----------|-----------|\n| SKILL.md exceeds | 100 lines | Maintain single-screen readability |\n| Content has distinct domains | N/A | Finance vs. sales schemas require separate handling |\n| Advanced features are rarely needed | N/A | Avoid cognitive overload for common use cases |\n\n资料来源：[skills/write-a-skill/SKILL.md:70-77]()\n\n## Workflow Documentation\n\n### Checklist Patterns\n\nFor complex tasks, use step-by-step checklists:\n\n```markdown\n## Workflows\n\n1. [ ] Prepare environment\n2. [ ] Validate inputs\n3. [ ] Execute operation\n4. [ ] Verify output\n5. [ ] Report results\n```\n\n### Mode Tables\n\nDocument different operational modes using tables:\n\n| Mode | Output | When |\n|------|--------|------|\n| `default` | Full operation | Normal use |\n| `quick` | Minimal output | Time-constrained scenarios |\n| `verbose` | Detailed diagnostics | Debugging |\n\n## Skill Lifecycle\n\n### Crystallization Workflow\n\nNew skills often emerge from successful problem-solving sessions. The crystallization workflow formalizes this knowledge capture:\n\n```mermaid\ngraph TD\n    A[T] --> B{Should this recur?}\n    B -->|yes| C[Review session]\n    B -->|no| D[Done]\n    C --> E[Extract pattern]\n    E --> F[Check scope]\n    F --> G{Search existing skills}\n    G -->|overlap found| H[Update existing]\n    G -->|no overlap| I[Create new skill]\n    H --> J[Log crystallization]\n    I --> J\n```\n\n资料来源：[skills/crystallize/SKILL.md:45-60]()\n\n### Crystallization Modes\n\n| Mode | Output | Trigger Phrases |\n|------|--------|-----------------|\n| `default` | Full crystallization | `crystallize`, `capture this as a skill` |\n| `quick` | Minimal skill stub | `quick crystallize`, mid-task pattern discovery |\n| `exploratory` | Expanded pattern capture | `--exploratory-mode`, `more crystallization` |\n| `drag-response` | Immediate capture | `this took too long`, `why aren't you using...` |\n| `correction` | Immediate update | Operator correction |\n| `audit` | Gap analysis | `what patterns did we miss` |\n\n资料来源：[skills/crystallize/SKILL.md:63-72]()\n\n## Review Checklist\n\nBefore finalizing a skill, verify the following:\n\n| Item | Requirement | Validation |\n|------|-------------|------------|\n| Description | Includes triggers (\"Use when...\") | Check second sentence format |\n| Length | SKILL.md under 100 lines | Line count |\n| Timelessness | No time-sensitive info | Scan for dates, deadlines |\n| Terminology | Consistent naming | Cross-reference glossary |\n| Examples | Concrete use cases included | At least one working example |\n| Depth | References one level deep | Check cross-links |\n\n资料来源：[skills/write-a-skill/SKILL.md:79-87]()\n\n## Artifact Routing\n\nSkills should specify where outputs and artifacts are stored:\n\n| Artifact | Path Pattern | Purpose |\n|----------|--------------|---------|\n| New skill | `~/.agents/skills/<slug>/SKILL.md` | Reusable capability |\n| Updated skill | Same path as existing | Extended capability |\n| Crystallization log | `docs/plans/crystallization-log.md` | History tracking |\n\n资料来源：[skills/crystallize/SKILL.md:76-81]()\n\n## Integration with Agent Context\n\n### Relationship to SP-006\n\nThe `crystallize` skill complements SP-006 (latent skill observer) by adding **intentional** crystallization from reasoning. While SP-006 automatically detects patterns from tool call sequences, this skill captures patterns from understanding the problem domain. Both mechanisms feed the same skill namespace. 资料来源：[skills/crystallize/SKILL.md:84-88]()\n\n### Context Loading\n\nSkills should integrate with the broader agent context system:\n\n```mermaid\ngraph LR\n    A[Agent Request] --> B[Skill Loader]\n    B --> C{Skill Description Match?}\n    C -->|yes| D[Load SKILL.md]\n    C -->|no| E[Continue Search]\n    D --> F[Execute Workflow]\n```\n\nSkills are discovered through description matching, not file naming. The agent evaluates the `description` field against the current request context.\n\n## Best Practices\n\n### Naming Conventions\n\n| Element | Convention | Example |\n|---------|------------|---------|\n| Skill directory | kebab-case | `pdf-extract` |\n| Skill name | lowercase, hyphenated | `pdf-extract` |\n| Script files | camelCase or kebab-case | `helper.js`, `validate-input.js` |\n| Reference docs | Title Case | `REFERENCE.md` |\n\n### Error Handling\n\n| Error Type | Recommended Approach |\n|------------|---------------------|\n| Validation failure | Provide clear error message with correction guidance |\n| Missing dependencies | Document prerequisites in SKILL.md |\n| Runtime errors | Include troubleshooting section |\n\n### Documentation Depth\n\nMaintain appropriate abstraction levels:\n\n- **SKILL.md**: Quick reference, common workflows\n- **REFERENCE.md**: Edge cases, API details, advanced configuration\n- **scripts/**: Implementations, not documentation\n\n## Related Skills\n\n| Skill | Relationship | Purpose |\n|-------|--------------|---------|\n| `crystallize` | Companion | Pattern extraction from sessions |\n| `skill-surgery-rd` | Operational | Skill maintenance and auditing |\n| `shadow-refactor` | Pattern source | Refactoring patterns become skills |\n\n资料来源：[skills/skill-surgery-rd/SKILL.md:1-10]()\n\n## Contract\n\nWhen authoring skills, adhere to these principles:\n\n1. **Do not invent behavior** not supported by the source files\n2. **Cite all claims** using the format `资料来源：[path/to/file.ext:line-line]()`\n3. **Preserve operator boundaries** when consolidating domain-specific skills\n4. **Externalize reports** to appropriate artifact paths\n\n资料来源：[skills/skill-surgery-rd/SKILL.md:110-118]()\n\n---\n\n<a id='crystallize'></a>\n\n## Crystallize - Pattern Extraction\n\n### 相关页面\n\n相关主题：[Agent Crystallization Protocol](#agent-cryst), [Write A Skill - Authoring Guide](#write-a-skill), [Skill Surgery R&D](#skill-surgery-rd)\n\n<details>\n<summary>Related Source Files</summary>\n\nThe following source files were used to generate this documentation:\n\n- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n</details>\n\n# Crystallize - Pattern Extraction\n\n## Overview\n\nCrystallize is a systematic skill for extracting reusable patterns from completed task sessions and capturing them as persistent, reusable skills. It transforms tacit knowledge gained during problem-solving into explicit, structured documentation that can be leveraged in future tasks.\n\nThe Crystallize skill serves as a complementary mechanism to SP-006 (latent skill observer), which automatically detects patterns from tool call sequences. While SP-006 observes tool usage, Crystallize adds **intentional** extraction from reasoning—patterns that emerge from understanding the problem domain, not just from observing execution traces.\n\n## Core Purpose\n\nThe primary objectives of Crystallize are:\n\n| Objective | Description |\n|-----------|-------------|\n| **Knowledge Capture** | Transform implicit problem-solving knowledge into explicit documentation |\n| **Reuse Enablement** | Create persistent skills that can be triggered in similar future contexts |\n| **Pattern Standardization** | Establish consistent structures for skill documentation |\n| **Continuous Improvement** | Build a growing library of battle-tested patterns |\n\n## Workflow\n\nThe Crystallize process follows a structured decision tree that determines whether a pattern warrants extraction and how it should be documented.\n\n```mermaid\ngraph TD\n    A[Task Complete] --> B{Should this recur?}\n    B -->|Yes| C[Review Session]\n    B -->|No| Z[Done]\n    C --> D[Extract Pattern]\n    D --> E[Check Scope]\n    E --> F[Search Existing Skills]\n    F -->|Overlap Found| G[Update Existing]\n    F -->|No Overlap| H[Create New Skill]\n    G --> I[Log Crystallization]\n    H --> I\n    I --> Z\n```\n\n### Phase 1: Review\n\nThe review phase establishes context by answering fundamental questions about the completed task:\n\n- **What was the task?** — Define the original objective\n- **What problem was solved?** — Identify the core challenge\n- **What did I learn?** — Extract the key insight or technique\n- **What steps would I repeat next time?** — Determine the reusable sequence\n\n资料来源：[skills/crystallize/SKILL.md:1-20]()\n\n### Phase 2: Pattern Extraction\n\nThis phase identifies the reusable elements from the completed session:\n\n| Element | Description |\n|---------|-------------|\n| **Key Steps** | Minimal sequence that produces the result |\n| **Heuristics** | Judgment calls, rules of thumb that emerged |\n| **Gotchas** | What went wrong or nearly went wrong; assumptions that failed |\n| **Decision Points** | Where approaches were chosen; what determined the choice |\n\n### Phase 3: Scope Check\n\nDetermine whether the pattern is:\n\n- **General** — Applicable across multiple domains or tasks\n- **Domain-Specific** — Limited to a particular technology, framework, or context\n\n### Phase 4: Deduplication\n\nSearch existing skills to prevent overlap:\n\n1. Check for similar trigger phrases in other skill descriptions\n2. Evaluate whether the pattern extends or supersedes existing skills\n3. Make the create-vs-update decision\n\n### Phase 5: Create or Update Skill\n\n#### Creating a New Skill\n\nPlace skills in the appropriate location based on scope:\n\n| Scope | Location |\n|-------|----------|\n| General patterns | `~/.agents/skills/<skill-name>/SKILL.md` |\n| Enterprise-specific | `~/.agents/skills/<enterprise-subdirectory>/` |\n\n#### Updating an Existing Skill\n\nWhen overlap is found, add the new pattern as a new section or extend the existing workflow. Preserve the skill's existing structure while integrating the new information.\n\n### Phase 6: Log the Crystallization\n\nRecord metadata at the bottom of the skill under `## Crystallized From`:\n\n```markdown\n## Crystallized From\n- Session: [date/context]\n- Original task: [what was being solved]\n- Pattern extracted: [what pattern was extracted]\n- Exploratory mode notes: [adjacent surfaces checked and left untouched]\n```\n\n## Crystallization Modes\n\nThe Crystallize skill supports multiple operational modes to handle different crystallization scenarios:\n\n| Mode | Output | Trigger Phrases |\n|------|--------|-----------------|\n| `default` | Full crystallization: review → extract → scope → deduplicate → create/update | `crystallize`, `capture this as a skill` |\n| `quick` | Fast capture to a minimal skill stub (full refinement later) | `quick crystallize`, `mid-task pattern discovery` |\n| `exploratory` | Expand one ring outward; check adjacent surfaces for same pattern | `--exploratory-mode`, `more crystallization` |\n| `drag-response` | Immediate crystallization triggered by operator frustration | `this took too long`, `why aren't you using...` |\n| `correction` | Immediate update from operator correction | Operator corrects an identity/path/boundary |\n| `audit` | Check what should have been crystallized but wasn't | `what patterns did we miss` |\n\n### Exploratory-Mode Expansion\n\nWhen the operator requests exploratory mode, do not stop at the first local fix. Expand one ring outward using this sweep:\n\n1. Start from the exact thing that was fixed\n2. Check the nearest adjacent surfaces that could carry the same stale assumption\n3. Capture the broader reusable rule\n\n## Artifact Routing\n\nAll crystallization artifacts are routed to specific locations based on their type and purpose:\n\n| Artifact Type | Path | Purpose |\n|---------------|------|---------|\n| New skill | `~/.agents/skills/<slug>/SKILL.md` | Reusable capability |\n| Updated skill | Same path as existing skill | Extended capability |\n| Crystallization log | `docs/plans/crystallization-log.md` | History of all crystallizations (optional) |\n| Enterprise-specific skill | Appropriate `~/.agents/skills/` subdirectory | Domain-scoped capability |\n\n## SKILL.md Template\n\nWhen creating a new crystallized skill, use this structure:\n\n```markdown\n# Skill Name\n\nOne-line description. Use when [trigger phrases].\n\n## When to Use\n- [trigger 1]\n- [trigger 2]\n- [trigger 3]\n\n## Workflow\n1. [Step 1]\n2. [Step 2]\n3. [Step 3]\n\n## Key Decisions\n- [Decision point 1]: [default choice + why]\n- [Decision point 2]: [default choice + why]\n\n## Gotchas\n- [Common mistake 1]\n- [Common mistake 2]\n\n## Crystallized From\n- Session: [date/context]\n- Original task: [what was being solved]\n```\n\n## Fallback Chain\n\nWhen primary methods are unavailable, Crystallize follows a fallback chain:\n\n1. **Primary:** Full workflow — review → extract → scope → deduplicate → create/update\n2. **Quick mode unavailable:** Capture to minimal stub\n3. **Existing skills check fails:** Create new skill without deduplication check\n4. **Logging unavailable:** Skip optional crystallization log entry\n\n## Relationship with SP-006\n\n| Aspect | SP-006 | Crystallize |\n|--------|--------|-------------|\n| Detection Method | Automatic tool call sequence analysis | Intentional reasoning-based extraction |\n| Input | Tool usage patterns | Session review and understanding |\n| Trigger | Passive observation | Active decision to crystallize |\n| Output | Latent skill candidates | Explicit, documented skills |\n\nBoth mechanisms feed the same skill namespace, meaning patterns captured via Crystallize become available alongside automatically detected patterns from SP-006.\n\n## Best Practices\n\n1. **Capture decision rationale** — Not just what was done, but why it was chosen over alternatives\n2. **Include failure modes** — Document what assumptions failed and what went wrong\n3. **Be specific with triggers** — Include exact phrases that should activate the skill\n4. **Maintain minimal examples** — Keep the workflow concise; detailed reference material can be separate files\n5. **Log the crystallization context** — Future maintainers need to understand the original problem\n\n---\n\n<a id='skill-surgery-rd'></a>\n\n## Skill Surgery R&D\n\n### 相关页面\n\n相关主题：[Crystallize - Pattern Extraction](#crystallize), [Write A Skill - Authoring Guide](#write-a-skill)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n- [skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)\n- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n- [skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n- [skills/shadow-engg/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-engg/SKILL.md)\n</details>\n\n# Skill Surgery R&D\n\n## Overview\n\nSkill Surgery R&D is a specialized operational capability within the shadow-verse ecosystem designed to audit, maintain, and optimize the skill garden. It provides structured workflows for analyzing skill inventory, detecting overlaps, identifying gaps, and performing surgical interventions on skill files.\n\n**Purpose**: The skill serves as a meta-level operations layer that ensures the skill ecosystem remains healthy, non-redundant, and properly aligned with user intents.\n\n**Scope**: Skill Surgery R&D operates across the entire skill inventory, examining both structural integrity and semantic coverage of installed skills.\n\n资料来源：[skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n\n## Architecture\n\n### Skill Surgery R&D Structure\n\n```\nskill-surgery-rd/\n├── SKILL.md                              (main skill definition)\n├── scripts/\n│   ├── audit-skills.mjs                  (inventory scanner)\n│   └── redirect-deprecated-skill.mjs     (redirect migration)\n├── data/skill-rd/\n│   ├── skill-inventory.json              (machine-readable catalog)\n│   └── semantic-duplicate-clusters.json   (overlap analysis)\n└── ShadowArchive/80-reports/\n    └── skill-rd-YYYY-MM-DD.md            (surgery reports)\n```\n\n### Skill Classification Taxonomy\n\nThe system classifies skills into the following categories for surgical planning:\n\n| Category | Definition | Treatment |\n|----------|------------|-----------|\n| `trigger-deprecated` | Deprecated skill that still receives lookups | Redirect to canonical skill |\n| `trigger-repair` | Skill with weak \"Use when...\" triggers | Rewrite frontmatter description |\n| `overlap` | Multiple skills cover same user intent | Merge candidates |\n| `stale-lane` | Legacy skill with active-looking instructions but no active trigger | Deprecate gracefully |\n| `runtime-gap` | Workflow described but lacks deterministic scripts | Create helper scripts |\n\n资料来源：[skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n\n## Operational Modes\n\nSkill Surgery R&D supports multiple operational modes for different use cases:\n\n| Mode | Output | When to Use |\n|------|--------|-------------|\n| `default` | Full audit → classify → propose surgeries | `skill surgery`, `audit skills` |\n| `inventory` | Scan and list all skills with metadata | `inventory skills`, `list skills` |\n| `gaps` | Gap classification only (no surgery) | `skill gaps`, `what's missing` |\n| `overlaps` | Overlap/duplicate detection | `duplicate skills`, `overlaps` |\n| `redirect <old> <new>` | Redirect deprecated skill to replacement | Specific redirect request |\n| `merge <a> <b>` | Merge two skills into canonical form | Specific merge request |\n| `trim <skill>` | Move detail from SKILL.md to REFERENCE.md | Specific trim request |\n| `research <topic>` | Research new skill candidates | `research skill for X` |\n\n资料来源：[skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n\n## Surgical Operations\n\n### Surgery Decision Workflow\n\n```mermaid\ngraph TD\n    A[Audit Skill Garden] --> B{Classification}\n    B -->|trigger-deprecated| C[Redirect Operation]\n    B -->|trigger-repair| D[Rewrite Frontmatter]\n    B -->|overlap| E[Merge Operation]\n    B -->|stale-lane| F[Trim + Deprecate]\n    B -->|runtime-gap| G[Create Scripts]\n    C --> H[Validate Changes]\n    D --> H\n    E --> H\n    F --> H\n    G --> H\n    H --> I[Report Outcomes]\n```\n\n### Surgery Types\n\n#### 1. Redirect\n\nRedirects a deprecated skill to its canonical replacement while preserving migration guidance.\n\n```bash\n# Redirect a deprecated skill\nnode /Users/sdluffy/.agents/skills/skill-surgery-rd/scripts/redirect-deprecated-skill.mjs \\\n  --mapping=data/skill-rd/map.json\n```\n\n**Validation criteria**:\n- Confirm target canonical skill exists\n- Preserve migration notes in redirect\n- Verify no active triggers point to deprecated path\n\n#### 2. Trigger Repair\n\nRewrites the frontmatter description with concrete \"Use when...\" triggers.\n\n**Before**:\n```yaml\n---\nname: document-skill\ndescription: Helps with documents.\n---\n```\n\n**After**:\n```yaml\n---\nname: document-skill\ndescription: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.\n---\n```\n\n#### 3. Trim\n\nMoves rare detail from `SKILL.md` to `REFERENCE.md` when the main file exceeds 100 lines.\n\n**Trigger conditions**:\n- SKILL.md exceeds 100 lines\n- Content has distinct domains\n- Advanced features are rarely needed\n\n#### 4. Merge\n\nConsolidates overlapping skills after confirming one canonical owner and preserving useful gotchas.\n\n**Merge criteria**:\n- One canonical owner identified\n- Non-overlapping useful gotchas exist\n- Semantic duplication confirmed\n\n#### 5. Create\n\nCreates new skills only when no existing skill owns the lane.\n\n**Research requirements**:\n- Verify current docs or product state first\n- Store source links and date in companion `RESEARCH.md`\n- Never crystallize stale version numbers without freshness note\n\n资料来源：[skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n\n## Bundled Scripts\n\n### Audit Skills Script\n\nGenerates JSON reports for the skill inventory:\n\n```bash\nnode /Users/sdluffy/.agents/skills/skill-surgery-rd/scripts/audit-skills.mjs \\\n  --out=data/skill-rd\n```\n\n**Outputs**:\n| Artifact | Path | Purpose |\n|----------|------|---------|\n| Skill inventory | `data/skill-rd/skill-inventory.json` | Machine-readable catalog |\n| Duplicate clusters | `data/skill-rd/semantic-duplicate-clusters.json` | Overlap analysis |\n\n### Redirect Deprecated Skill Script\n\nDry-run or apply reversible redirects from a mapping file:\n\n```bash\n# Dry run\nnode /Users/sdluffy/.agents/skills/skill-surgery-rd/scripts/redirect-deprecated-skill.mjs \\\n  --mapping=data/skill-rd/map.json --dry-run\n\n# Apply\nnode /Users/sdluffy/.agents/skills/skill-surgery-rd/scripts/redirect-deprecated-skill.mjs \\\n  --mapping=data/skill-rd/map.json\n```\n\n资料来源：[skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n\n## Artifact Routing\n\nAll surgery artifacts follow a standardized routing structure:\n\n| Artifact | Path | Purpose |\n|----------|------|---------|\n| Skill inventory | `data/skill-rd/skill-inventory.json` | Machine-readable catalog |\n| Duplicate clusters | `data/skill-rd/semantic-duplicate-clusters.json` | Overlap map |\n| Surgery report | `ShadowArchive/80-reports/skill-rd-YYYY-MM-DD.md` | Session summary |\n| Updated SKILL.md files | Original locations | The surgeries themselves |\n\n资料来源：[skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n\n## Validation Protocol\n\n### Review Checklist\n\nAfter drafting surgical changes, verify:\n\n- [ ] Triggers include \"Use when...\" patterns\n- [ ] SKILL.md under 100 lines\n- [ ] No time-sensitive info hardcoded\n- [ ] Consistent terminology throughout\n- [ ] Concrete examples included\n- [ ] References one level deep (no circular dependencies)\n\n### Validation Steps\n\n1. **Run skill validation** when available\n2. **Execute deterministic helper scripts** for generated inventories\n3. **Report bounded completion**: files changed, evidence used, residual risk, next check date\n\n资料来源：[skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n\n## Fallback Chain\n\nWhen primary operations fail, Skill Surgery R&D follows a recovery hierarchy:\n\n```mermaid\ngraph TD\n    A[Full Scan] --> B{Skills dir found?}\n    B -->|Yes| C{Scan results?}\n    B -->|No| D[Check alternate paths]\n    D --> E{Local scan?}\n    E -->|Yes| C\n    E -->|No| F[Report path issue]\n    C -->|Empty| G[Report empty inventory]\n    C -->|Has data| H[Analyze + Report]\n```\n\n| Failure | Recovery |\n|---------|----------|\n| Skills directory not found | Check alternate paths; report; scan what's available |\n| Memory directory empty | Report; note no session history available |\n| Caresoft API returns error | Report API failure; skip engineering mode |\n| Skills directory empty | Report; likely path issue; suggest checking `~/.agents/skills/` |\n\n资料来源：[skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n\n## Relationship to Other Skills\n\n### Integration with Crystallize\n\nSkill Surgery R&D complements SP-006 (latent skill observer) by adding **intentional** crystallization from reasoning. Both mechanisms feed the same skill namespace:\n\n| Mechanism | Source | Trigger |\n|-----------|--------|---------|\n| SP-006 | Tool call sequence observation | Automatic pattern detection |\n| Skill Surgery R&D | Intentional analysis | Manual or explicit crystallization |\n\n### Integration with Shadow Refactor\n\nBoth skills share the refactoring philosophy:\n\n| Aspect | Skill Surgery R&D | Shadow Refactor |\n|--------|-------------------|-----------------|\n| Focus | Skill metadata and triggers | Code structure and patterns |\n| Target | `SKILL.md` files | Source code files |\n| Validation | Bounded completion report | Test pass verification |\n\n资料来源：[skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md), [skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)\n\n## Prerequisites\n\n- Access to skill directories (`~/.agents/skills/`, `.agents/skills/`)\n- ShadowArchive volume mounted for reports (optional for local-only mode)\n- `node` runtime for bundled scripts\n- `grep`, `find`, `wc` for pattern analysis\n- Access to `ShadowArchive/80-reports/` for reports\n\n## Usage Examples\n\n### Full Skill Audit\n\n```bash\n# Trigger default mode: full audit\nskill-surgery audit\n```\n\n### Quick Inventory Check\n\n```bash\n# List all skills with metadata\nskill-surgery inventory\n```\n\n### Gap Analysis\n\n```bash\n# Find what's missing\nskill-surgery gaps\n```\n\n### Find Overlaps\n\n```bash\n# Detect duplicate skills\nskill-surgery overlaps\n```\n\n### Redirect Deprecated Skill\n\n```bash\n# Redirect old skill to new canonical skill\nskill-surgery redirect old-skill-name new-skill-name\n```\n\n### Research New Skill\n\n```bash\n# Investigate skill for a topic\nskill-surgery research \"automotive engineering\"\n```\n\n资料来源：[skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：s4b7-ai/s4b7-ai-skills\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `s4b7-ai-skills` 与安装入口 `skills` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npx skills`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | repo=s4b7-ai-skills; install=skills\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | release_recency=unknown\n\n<!-- canonical_name: s4b7-ai/s4b7-ai-skills; human_manual_source: deepwiki_human_wiki -->\n",
      "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
      "title": "Human Manual / 人类版说明书"
    },
    "pitfall_log": {
      "asset_id": "pitfall_log",
      "filename": "PITFALL_LOG.md",
      "markdown": "# Pitfall Log / 踩坑日志\n\n项目：s4b7-ai/s4b7-ai-skills\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `s4b7-ai-skills` 与安装入口 `skills` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npx skills`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | repo=s4b7-ai-skills; install=skills\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | release_recency=unknown\n",
      "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
      "title": "Pitfall Log / 踩坑日志"
    },
    "prompt_preview": {
      "asset_id": "prompt_preview",
      "filename": "PROMPT_PREVIEW.md",
      "markdown": "# s4b7-ai-skills - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for s4b7-ai/s4b7-ai-skills.\n\nProject:\n- Name: s4b7-ai-skills\n- Repository: https://github.com/s4b7-ai/s4b7-ai-skills\n- Summary: Agent skills for AI/ML workflows — model orchestration, multi-model inference, agent building, policy steering, and self-improvement loops.\n- Host target: local_cli\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Agent skills for AI/ML workflows — model orchestration, multi-model inference, agent building, policy steering, and self-improvement loops.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n- Capability 2: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. skill-structure: Skill Structure & Anatomy. Produce one small intermediate artifact and wait for confirmation.\n2. langgraph-agent: LangGraph Agent Development. Produce one small intermediate artifact and wait for confirmation.\n3. ai-sdk-core: AI SDK Core - Vercel Integration. Produce one small intermediate artifact and wait for confirmation.\n4. write-a-skill: Write A Skill - Authoring Guide. Produce one small intermediate artifact and wait for confirmation.\n5. crystallize: Crystallize - Pattern Extraction. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/s4b7-ai/s4b7-ai-skills\n- https://github.com/s4b7-ai/s4b7-ai-skills#readme\n- skills/a2a-orchestrator/SKILL.md\n- skills/aacp/SKILL.md\n- skills/acp-delegate-auto/SKILL.md\n- skills/agent-cryst/SKILL.md\n- skills/ai-sdk-core/SKILL.md\n- skills/codex-context/SKILL.md\n- skills/codex-latex/SKILL.md\n- skills/codex-policy-steering/SKILL.md\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
      "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
      "title": "Prompt Preview / 安装前试用 Prompt"
    },
    "quick_start": {
      "asset_id": "quick_start",
      "filename": "QUICK_START.md",
      "markdown": "# Quick Start / 官方入口\n\n项目：s4b7-ai/s4b7-ai-skills\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx skills\n```\n\n来源：https://github.com/s4b7-ai/s4b7-ai-skills#readme\n\n## 来源\n\n- repo: https://github.com/s4b7-ai/s4b7-ai-skills\n- docs: https://github.com/s4b7-ai/s4b7-ai-skills#readme\n",
      "summary": "从项目官方 README 或安装文档提取的开工入口。",
      "title": "Quick Start / 官方入口"
    }
  },
  "validation_id": "dval_b4079d7060694641894b0f348329da88"
}