AI技能分发工具

印记

通过NuGet包分发AI技能和MCP配置

概述

印记是一种分配人工智能技能的模式（那些 SKILLS.md GitHub Copilot、Claude、Cursor、Roo Code、Kiro和其他AI助手的文件）和MCP服务器配置（通过NuGet包）。将Imprint包添加到项目中时：

1. 开 dotnet build：技能会自动复制到每个AI代理的本地目录中
2. 开 dotnet clean：技能被删除（包括空父目录）
3. 多代理支持：同时针对Copilot、Claude、Cursor、Roo Code、OpenCode、Kiro和Windsurf——每个都在其本机位置（如果存在）获取文件
4. 支持的所有文件类型：不只是 .md --脚本、配置和中的任何其他文件 skills/ 包含文件夹
5. MCP服务器注入：包可以注入 MCP（模型上下文协议） 每个代理的服务器配置 mcp.json
6. 代码+技能：软件包可以附带已编译的DLL库 和 AI技能——消费者从单个NuGet安装中获得运行时API和AI指导

这可以实现以下场景：

• 合规技能：全组织编码标准打包分发
• 框架技能：特定框架的最佳实践（例如Azure、EF Core）
• 团队技能：跨团队项目共享知识
• MCP服务器：将MCP服务器配置与技能一起发布——消费者从单个NuGet安装中获得AI知识和工具访问权限
• 图书馆+技能：发布一个实用程序库，其中包含有关如何使用它的人工智能指导

库作者可以选择消费者是选择加入还是退出技能和MCP片段。通过设置 ImprintEnabledByDefault 在包裹的 .csproj，作者控制默认行为：

<PropertyGroup>
  <ImprintEnabledByDefault>false</ImprintEnabledByDefault> <!-- Opt-in: disabled unless user enables -->
</PropertyGroup>

消费者始终可以使用其上的元数据覆盖每个包 PackageReference:

<PackageReference Include="SomePackage" Version="1.0.0">
  <ImprintEnabled>false</ImprintEnabled> <!-- Disable or enable this package's skills/MCP -->
</PackageReference>

消费者的显式设置始终优先于包作者的默认设置。

快速开始

使用印记包装

# Add the package
dotnet add package <some-Imprint-package>

# Build to install skills (happens automatically before build)
dotnet build

# Skills are now at .github/skills/, .claude/skills/, .cursor/rules/, .kiro/skills/ etc.

Imprint通过扫描配置目录自动检测您使用的AI代理(.github/, .claude/, .cursor/, .roo/, .opencode/, .windsurf/, .kiro/).技能被复制到每个检测到的代理的本地位置。

A共享 .gitignore 在以下时间自动生成 .imprint/.gitignore，所以没有手册 .gitignore 需要配置。

创建自己的印记包

创建新的类库项目并添加 <Imprint> 用于声明内容的项目：

<Project Sdk="Microsoft.NET.Sdk">
  <ItemGroup>
    <PackageReference Include="Zakira.Imprint.Sdk" Version="1.0.0-preview" />
  </ItemGroup>

  <!-- Declare your content using <Imprint> items -->
  <ItemGroup>
    <Imprint Include="skills\**\*" /> 
    <Imprint Include="mcp\*.mcp.json" Type="Mcp" />             <!-- MCP server configs -->
  </ItemGroup>
</Project>

创造你的技能 skills/ 文件夹，然后打包：

dotnet pack -o ./packages

SDK会自动生成 .targets 打包时的文件--不需要手动编写MSBuild！

多代理支持

Imprint包括多代理支持。Imprint不仅可以针对GitHub Copilot，还可以将技能和MCP配置分发给 多个AI代理同时，将文件放置在每个代理的本机目录结构中。

支持的代理

未知的代理名称可以追溯到 .{name}/rules/ 对于技能和 .{name}/mcp.json 对于MCP。

代理人决议

Imprint使用优先级层次结构确定要针对哪些代理：

1. 显式配置 --设置 ImprintTargetAgents 在你的 .csproj:

   复制

   <PropertyGroup>
     <ImprintTargetAgents>claude;cursor</ImprintTargetAgents>
   </PropertyGroup>
   

2. 自动检测 （默认，ON）--在生成时扫描代理目录。如果 .github/ 和 .claude/ 存在，两者皆有 copilot 和 claude 成为目标。 支持的检测目录： .github/ （副驾驶）， .claude/ （克劳德）， .cursor/ （光标）， .roo/ （roo）， .opencode/ （开放代码）， .windsurf/ （风帆）， .agents/ （代理人）， .kiro/ （公斤）。

3. 默认回退 --如果未检测到目录：

   复制

   <PropertyGroup>
     <ImprintDefaultAgents>copilot</ImprintDefaultAgents>
   </PropertyGroup>
   

配置属性

根目录

默认情况下，Imprint自动检测 存储库根目录 从项目目录中向上走。标记按优先级顺序检查：

1. VCS目录 - .git/, .svn/, .hg/ （最权威）
2. IDE目录 - .vs/ （Visual Studio）， .idea/ （JetBrains）
3. 解决方案文件 - *.sln, *.slnx （回退）

这确保了在多项目解决方案中，技能被放置在存储库根（其中 .git/ lives）而不是在单个项目目录中：

/repo-root/              <-- Skills placed here (correct)
├── .git/
├── .github/skills/      <-- Not inside src/MyProject/.github/
├── src/
│   └── MyProject/
│       └── MyProject.csproj
└── MyApp.sln

如果自动检测不适用于您的设置，您可以显式设置根目录：

<PropertyGroup>
  <ImprintRootDirectory>$(MSBuildThisFileDirectory)..\</ImprintRootDirectory>
</PropertyGroup>

如果找不到存储库根，也没有设置显式覆盖，则Imprint将回退到项目目录。

输出示例

随着 .github/ 和 .claude/ 目录存在，正在安装 Zakira.Imprint.Sample 生产：

.github/
  skills/
    personal/
      SKILL.md              # Copilot sees this
.claude/
  skills/
    personal/
      SKILL.md              # Claude sees this
.vscode/
  mcp.json                  # MCP servers for Copilot/VS Code
.claude/
  mcp.json                  # MCP servers for Claude
.imprint/
  manifest.json             # Unified tracking manifest (v2)
  .gitignore                # Prevents tracking of managed files

可用包

运作原理

建筑

所有Imprint技能包取决于 扎奇拉。Imprint.Sdk，它提供MSBuild任务引擎。包作者声明 <Imprint> 他们的物品 .csproj --SDK自动生成 .targets 在打包时处理文件，然后在构建/清理时处理代理解析、文件复制、MCP合并、清单跟踪和清理。

┌───────────────────────────┐  ┌────────────────────────────────────┐
│  Sample                   │  │  Sample.FilesOnly                  │
│  (skills + MCP + code)    │  │  (skills-only)                     │
└──────┬────────────────────┘  └──────┬─────────────────────────────┘
       │                              │
       ▼                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│  Zakira.Imprint.Sdk                                                 │
│  - Auto-generates .targets at pack time (ImprintGenerateTargets)    │
│  - Copies skills to all agents (ImprintCopyContent)                 │
│  - Merges MCP servers (ImprintMergeMcpServers)                      │
│  - Cleans on dotnet clean (ImprintCleanContent, ImprintCleanMcp)    │
└─────────────────────────────────────────────────────────────────────┘

构建时间流

1. NuGet还原：NuGet恢复技能包，这些技能包可传递地拉入 Zakira.Imprint.SdkMSBuild通过以下方式自动导入SDK的道具和目标 buildTransitive/ 文件夹。

2. 代理人决议：在任何文件操作之前， AgentConfig.ResolveAgents() 确定要针对哪些代理：

   • 如果 ImprintTargetAgents 已设置，请使用该显式列表
   • 否则如果 ImprintAutoDetectAgents 如果为真，请扫描 .github/, .claude/, .cursor/, .roo/, .opencode/, .windsurf/ 目录
   • 否则，请返回 ImprintDefaultAgents

3. 内容复制 (Imprint_CopyContent)：对于每个已解析的代理，将技能文件复制到代理的本机技能目录。在以下位置写入统一清单v2 .imprint/manifest.json 跟踪每个代理每个包的所有文件。这些副本和共享 .gitignore/清单写入在并行、多项目构建下是安全的：跳过已经与源匹配的目标，并使用回退和协调重新尝试并发写入，因此构建一个解决方案 -m 不会因“文件正被另一个进程使用”错误而失败。

4. MCP合并 (Imprint_MergeMcp)：将MCP服务器片段合并到每个代理的 mcp.json。跟踪统一清单中的托管服务器密钥。

5. 清洁 (Imprint_CleanContent + Imprint_CleanMcp)：读取统一清单，仅删除跟踪的文件和托管的MCP服务器。删除空目录。保留用户定义的MCP服务器。

包装时间流

当你奔跑时 dotnet pack 在您的Imprint包装上：

1. 生成目标 (Imprint_GenerateTargetsFile)：SDK读取所有 <Imprint> 您的物品 .csproj 并生成 .targets 文件在 obj/{Configuration}/{TFM}/Imprint/{PackageId}.targets。此文件声明 ImprintContent 和 ImprintMcpFragment 消费者将使用的物品。

2. 包含内容+交叉定向导入 (Imprint_IncludeContentInPackage)：SDK添加生成的 .targets 文件到两者 build/ 和 buildTransitive/ 包路径，包括中的所有内容文件（技能、MCP片段） content/ 文件夹，适用于多目标包项目(<TargetFrameworks>...)进口通过 buildMultiTargeting/ 在外部包构建中，以便Imprint包目标可以在之前运行 _GetPackageFiles.

3. NuGet包：该包是使用所有必要的文件创建的，无需手动 .targets 需要创作。

统一清单（v2）

Imprint在以下位置使用单一清单 .imprint/manifest.json 追踪一切：

{
  "version": 2,
  "packages": {
    "Zakira.Imprint.Sample": {
      "files": {
        "copilot": [".github/skills/personal/SKILL.md"],
        "claude": [".claude/skills/personal/SKILL.md"]
      }
    }
  },
  "mcp": {
    "copilot": {
      "path": ".vscode/mcp.json",
      "managedServers": ["sample-echo-server"]
    },
    "claude": {
      "path": ".claude/mcp.json",
      "managedServers": ["sample-echo-server"]
    }
  }
}

每个包裹的遗留问题 .manifest 文件仍然是为了向后兼容性而编写的。

MCP服务器注入

印记包可以提供MCP（模型上下文协议）服务器配置。构建时，服务器配置会自动合并到每个目标代理的配置中 mcp.json.

MCP注入的工作原理

1. 每个印记包包括 mcp/<PackageId>.mcp.json 包含其服务器定义的片段文件
2. 在构建时， Zakira.Imprint.Sdk 收集所有 ImprintMcpFragment 已安装软件包中的项目
3. 对于每个解析的代理，服务器都会合并到该代理的 mcp.json，保留您手动配置的任何服务器
4. 统一清单跟踪Imprint管理的服务器
5. 开 dotnet clean，只删除Imprint管理的服务器——您的服务器永远不会被触及

示例片段文件

印记包 mcp/<PackageId>.mcp.json:

{
  "servers": {
    "sample-echo-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/echo-mcp-server"]
    }
  }
}

备注：软件包作者总是使用 "servers" 作为片段文件中的根密钥。当写入每个代理的根密钥时，SDK会自动将其转换为每个代理的正确根密钥 mcp.json 文件夹。

之后 dotnet build 两者都 copilot 和 claude 检测到的代理：

• .vscode/mcp.json 包含以下服务器 "servers" （VS代码/副驾驶模式）
• .claude/mcp.json 包含以下服务器 "mcpServers" （克劳德模式）

关键行为

• 幂等：如果没有任何变化， mcp.json 未重写（无git噪声）
• 安全清洁: dotnet clean 仅删除托管服务器；如果没有用户服务器剩余， mcp.json 被删除
• 保留用户服务器：您手动添加到的任何服务器 mcp.json 从未被修改或删除
• inputs 保存的：顶级属性，如 "inputs" 在 mcp.json 通过构建和清洁来保存
• 多代理：每个代理都有自己的 mcp.json 在其原产地
• 模式转换：SDK会自动为每个代理使用正确的根密钥("servers" 对于Copilot， "mcpServers" 克劳德/Cursor）

MCP模式差异

不同的AI代理对其MCP配置文件使用不同的JSON模式。SDK会自动处理此问题：

包作者总是使用 "servers" 作为根密钥。SDK读取这些片段，并在写入各自的模式时将其转换为每个代理的预期模式 mcp.json 文件夹。内部服务器定义(command, args, type, env)在所有代理中都是相同的。

将MCP注射添加到您的包装中

1. 添加a PackageReference 到 Zakira.Imprint.Sdk 在你的 .csproj

2. 创建 mcp/<YourPackageId>.mcp.json 包含服务器定义的片段

3. 使用以下命令添加片段 <Imprint> 项目与 Type="Mcp":

<ItemGroup>
  <Imprint Include="skills\**\*" />                           <!-- Skills -->
  <Imprint Include="mcp\*.mcp.json" Type="Mcp" />             <!-- MCP fragments -->
</ItemGroup>

SDK自动生成 .targets 打包时的文件——无需手动配置！

两种包装模式

仅技能套餐

对于仅分发AI技能和MCP配置（无编译代码）的包：

<PropertyGroup>
  <IncludeBuildOutput>false</IncludeBuildOutput>
  <DevelopmentDependency>true</DevelopmentDependency>
</PropertyGroup>

看 samples/Sample.FilesOnly 举个例子。

代码+技能包

对于同时提供编译DLL的包 和 人工智能技能：

<PropertyGroup>
  <!-- IncludeBuildOutput defaults to true - DLL ships in lib/ -->
  <!-- Do NOT set DevelopmentDependency - consumers need the runtime DLL -->
</PropertyGroup>

看 samples/Sample 例如，它将字符串实用程序方法与AI技能文件和MCP服务器配置一起提供。

配置

代理定位

控制哪些AI代理Imprint目标：

<PropertyGroup>
  <!-- Target specific agents (overrides auto-detection) -->
  <ImprintTargetAgents>copilot;claude</ImprintTargetAgents>

  <!-- Or disable auto-detection and use only defaults -->
  <ImprintAutoDetectAgents>false</ImprintAutoDetectAgents>
  <ImprintDefaultAgents>copilot</ImprintDefaultAgents>
</PropertyGroup>

传统路径覆盖

这些属性仍然可用于向后兼容性，但通常会被多代理解析所取代：

测试此回购

# 1. Pack the SDK first, then samples (to local-packages/)
dotnet pack src/Zakira.Imprint.Sdk -o ./local-packages
dotnet pack samples/Sample -o ./local-packages
dotnet pack samples/Sample.FilesOnly -o ./local-packages

# 2. Create a test consumer (or use samples/Consumer)
cd samples/Consumer
dotnet build

# 3. Verify skills are installed (agent directories vary by your setup)
ls .github/skills/
# personal/  StringUtils/

# 4. Verify MCP servers were injected
cat .vscode/mcp.json
# { "servers": { "sample-echo-server": {...} } }

# 5. Run unit tests
cd ../..
dotnet test Zakira.Imprint.sln

# 6. Test clean - skills and managed MCP servers are removed
cd samples/Consumer
dotnet clean
ls .github/          # Should be empty or not exist
ls .vscode/mcp.json  # Should not exist (no user servers to preserve)

# 7. Build again - everything is restored
dotnet build

限制和已知问题

1. 包装移除：当您删除Imprint包时，其技能将一直保留，直到您运行 dotnet clean 或者手动删除它们。

2. IDE设计时构建：技能和MCP服务器仅在实际构建期间进行管理，而不是在IDE后台构建期间（这是为了避免性能问题）。

3. 需要首次构建：技能和MCP配置是在第一次构建时安装的，而不是在还原时安装的。

4. 共享输出文件夹：每个代理将多个包写入同一技能目录。如果两个包包含具有相同相对路径的文件，则最后一个复制的包获胜。

5. MCP服务器密钥冲突：如果两个Imprint包使用相同的密钥定义了一个服务器，则最后处理的片段将自动获胜。计划对此发出警告。

6. 扎奇拉。印记.Sdk需要。净值8+：扎奇拉。Imprint.Sdk编译任务DLL目标 net8.0消费者必须拥有。NET 8 SDK或更高版本已安装。

未来的增强功能

• [x] 一个项目中包含多个技能包
• [x] ~~ MCP服务器注入~~
• [x] 集中式SDK（Zakira.Imprint.SDK）--所有MSBuild逻辑的单一来源
• [x] 每个包裹清单用于精确的文件跟踪
• [x] 代码+技能包模式
• [x] ~~ MSBuild任务类的单元测试~~
• [x] 多代理支持（复制、Claude、Cursor、Roo代码）
• [x] 自动检测AI代理
• [x] 具有每个代理跟踪功能的统一清单v2
• [x] 自动生成 .targets 文件--不需要手动编写MSBuild
• [x] 多项目解决方案的存储库根自动检测
• []多个包定义相同密钥时的服务器密钥冲突检测/警告
• []跨解决方案管理技能的全球工具
• []包装过程中的技能验证
• []技能包之间的冲突检测
• []用于构建和发布软件包的CI/CD管道
• []提示支持（分发 .prompt 文件到特定于代理的目录）
• [x] ~~ Windsurf代理支持~~
• []额外的代理支持（Cody等）

许可证

麻省理工学院