印记

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

![Documentation](https://moaidhathot.github.io/Zakira.Imprint/)

概述

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

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

这可以实现以下场景：

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

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


  false

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


  false

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

快速开始

使用印记包装

# Add the package
dotnet add package 

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

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

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

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

创建自己的印记包

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


  
    

  

   items -->

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

dotnet pack -o ./packages

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

多代理支持

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

支持的代理

代理	检测	技能路径	MCP路径	MCP根密钥
`copilot`	`.github/` 存在	`.github/skills/`	`.vscode/mcp.json`	`servers`
`claude`	`.claude/` 存在	`.claude/skills/`	`.claude/mcp.json`	`mcpServers`
`cursor`	`.cursor/` 存在	`.cursor/rules/`	`.cursor/mcp.json`	`mcpServers`
`roo`	`.roo/` 存在	`.roo/rules/`	`.roo/mcp.json`	`mcpServers`
`opencode`	`.opencode/` 存在	`.opencode/skills/`	`opencode.json` （项目根）	`mcp`
`windsurf`	`.windsurf/` 存在	`.windsurf/rules/`	`.windsurf/mcp.json`	`mcpServers`
`agents`	`.agents/` 存在	`.agents/skills/`	`.agents/mcp.json`	`mcpServers`

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

代理解决方案

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

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

   

     claude;cursor

自动检测 （默认，ON）--在生成时扫描代理目录。如果 .github/ 和 .claude/ 存在，两者皆有 copilot 和 claude 成为目标。

支持的检测目录： .github/ （副驾驶）， .claude/ （克劳德）， .cursor/ （光标）， .roo/ （roo）， .opencode/ （开放代码）， .windsurf/ （风帆）， .agents/ （代理人）。

   

     copilot

配置属性

属性	默认值	目的
`ImprintTargetAgents`	（空）	显式代理列表（以分号分隔）。覆盖自动检测。
`ImprintAutoDetectAgents`	`true`	在生成时扫描代理目录
`ImprintDefaultAgents`	（空）	未检测到代理时回退
`ImprintRootDirectory`	（自动检测）	技能所在的存储库根。看根目录.

根目录

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

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

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

/repo-root/              $(MSBuildThisFileDirectory)..\

如果找不到存储库根，也没有设置显式覆盖，则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.Sdk	1.0.0-预览	核心MSBuild任务引擎--自动生成 `.targets`、内容复制、清理、MCP合并、多代理支持

运作原理

建筑

所有Imprint技能包取决于 扎奇拉。Imprint.Sdk，它提供MSBuild任务引擎。包作者声明 ` 他们的物品 .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)    │
└─────────────────────────────────────────────────────────────────────┘

构建时间流

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

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

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

内容复制 (Imprint_CopyContent)：对于每个已解析的代理，将技能文件复制到代理的本机技能目录。在以下位置写入统一清单v2 .imprint/manifest.json 跟踪每个代理每个包的所有文件。

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

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

包装时间流

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

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

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

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注入的工作原理

每个印记包包括 `mcp/

.mcp.json` 包含其服务器定义的片段文件

在构建时， Zakira.Imprint.Sdk 收集所有 ImprintMcpFragment 已安装软件包中的项目
对于每个解析的代理，服务器都会合并到该代理的 mcp.json，保留您手动配置的任何服务器
统一清单跟踪Imprint管理的服务器
开 dotnet clean，只删除Imprint管理的服务器——您的服务器永远不会被触及

示例片段文件

印记包 mcp/ .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会自动处理此问题：

代理	根密钥	示例
副驾驶（VS代码）	`servers`	`{"servers": {"my-server": {...}}}`
克劳德	`mcpServers`	`{"mcpServers": {"my-server": {...}}}`
光标	`mcpServers`	`{"mcpServers": {"my-server": {...}}}`
Roo代码	`mcpServers`	`{"mcpServers": {"my-server": {...}}}`
OpenCode	`mcp`	`{"mcp": {"my-server": {...}}}`
风帆冲浪	`mcpServers`	`{"mcpServers": {"my-server": {...}}}`

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

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

添加一个 PackageReference 到 Zakira.Imprint.Sdk 在你的 .csproj

创建一个 mcp/.mcp.json 包含服务器定义的片段

使用以下命令添加片段 ` 项目与 Type="Mcp"`:

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

两种包装模式

仅技能套餐

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


  false
  true

看 samples/Sample.FilesOnly 举个例子。

代码+技能包

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

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

配置

代理定位

控制哪些AI代理Imprint目标：


  
  copilot;claude

  
  false
  copilot

传统路径覆盖

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

属性	默认值	目的
`ImprintSkillsPath`	`.github/skills/`	传统：单一代理技能路径
`ImprintPromptsPath`	`.github/prompts/`	传统：单个代理提示路径
`ImprintMcpPath`	`.vscode/`	传统：单代理MCP路径

测试此回购

# 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

限制和已知问题

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

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

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

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

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

扎奇拉。印记.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等）

许可证

麻省理工学院

Zakira.Imprint

快速接入

详细介绍

印记

概述