从 MCP 到 Agent Skills，AI Ready 的 .NET 10 正当时

skill-name/
└── SKILL.md          # 必需

skill-name/
├── SKILL.md          # 必需：技能描述和使用说明
├── scripts/          # 可选：可执行脚本
│   └── tool.py
├── references/       # 可选：详细参考文档
│   └── REFERENCE.md
└── assets/          # 可选：静态资源
    └── template.json

---
name: skill-name
description: 描述技能功能和使用场景的文字，应包含帮助 Agent 识别相关任务的关键词
---

---
name: pdf-processing
description: Extract text from PDFs and merge multiple documents
license: MIT
compatibility: Requires Python 3.8+ and poppler-utils
metadata:
  author: your-org
  version: "1.0.0"
---

#:package PdfSharpCore@1.3.65
#:package Spectre.Console@0.49.1

// 入门：10 行代码的简单工具
#!/usr/bin/env dotnet
if (args.Length == 0) { Console.WriteLine("Hello, Agent!"); return; }
Console.WriteLine($"Processing: {args[0]}");

// 进阶：添加依赖和错误处理
#:package Newtonsoft.Json@13.0.3
using Newtonsoft.Json;
try { /* 处理逻辑 */ }
catch (Exception ex) { Console.Error.WriteLine(ex.Message); return 1; }

// 生产：发布为高性能可执行文件
#:property PublishAot=true
// 一行命令：dotnet publish -r win-x64

my-skill/
├── tool.py          # Agent 需要读取
├── requirements.txt # Agent 需要读取
└── README.md        # Agent 需要读取

my-skill/
└── scripts/
    └── tool.cs      # 依赖、逻辑、配置全在这里

// 编译时就能发现错误，而不是运行时崩溃
string pdfPath = args[0];  // Agent 知道这是字符串
int pageCount = GetPageCount(pdfPath);  // Agent 知道返回值是整数

// Python 中相同的错误可能运行时才暴露
# pdf_path = args[0]  # 类型不明确
# page_count = get_page_count(pdf_path)  # 返回值类型不明确

# Python 脚本启动
$ time python tool.py input.pdf
real    0m0.234s  # 需要加载解释器

# .NET File-Based App 启动
$ time dotnet tool.cs input.pdf
real    0m0.089s  # JIT 编译

# Native AOT 编译后
$ time ./tool input.pdf
real    0m0.012s  # 接近原生 C++ 性能

mkdir -p split-pdf/scripts
cd split-pdf

---
name: split-pdf
description: Split PDF files into separate single-page documents or extract specific page ranges. Use when you need to divide a PDF into multiple files, extract particular pages, or process PDF pages individually. Works with multi-page PDF documents.
license: MIT
---

# Split PDF

将 PDF 文件拆分为多个单页文件或提取指定页面范围。

## 使用场景

- 将多页 PDF 拆分为独立的单页文件
- 提取 PDF 的特定页面范围
- 需要单独处理 PDF 各个页面时

## 使用方法

使用 `scripts/split-pdf.cs` 脚本进行 PDF 拆分：

### 拆分页面
# 拆分所有页面
dotnet scripts/split-pdf.cs input.pdf output-dir/
# 拆分第 1-5 页
dotnet scripts/split-pdf.cs input.pdf output-dir/ 1-5


## 输出格式

拆分后的文件命名格式：`{原文件名}_page_{页码}.pdf`

## 依赖项

- PdfSharpCore 1.3.65 - PDF 操作核心库
- Spectre.Console 0.49.1 - 美化的控制台输出



**注意**：
- `name` 必须与目录名 `split-pdf` 完全一致
- `description` 包含关键词 "split", "PDF", "pages" 帮助 Agent 识别场景

#!/usr/bin/env dotnet
#:package PdfSharpCore@1.3.65
#:package Spectre.Console@0.49.1
#:property PublishAot=true

using PdfSharpCore.Pdf;
using PdfSharpCore.Pdf.IO;
using Spectre.Console;
using System;
using System.IO;

// ==================== 参数校验 ====================
if (args.Length < 2)
{
    AnsiConsole.MarkupLine("[red]错误: 参数不足[/]");
    AnsiConsole.MarkupLine("[yellow]用法: dotnet split-pdf.cs <PDF文件> <输出目录> [页面范围][/]");
    return 1;
}

var pdfPath = args[0];
var outputDir = args[1];
var pageRange = args.Length >= 3 ? args[2] : null;

// 验证文件
if (!File.Exists(pdfPath))
{
    AnsiConsole.MarkupLine($"[red]错误: 文件不存在: {pdfPath}[/]");
    return 1;
}

// 创建输出目录
Directory.CreateDirectory(outputDir);

// ==================== 拆分 PDF ====================
try
{
    using var inputDocument = PdfReader.Open(pdfPath, PdfDocumentOpenMode.Import);
    var totalPages = inputDocument.PageCount;
    
    // 解析页面范围
    int startPage = 1, endPage = totalPages;
    if (!string.IsNullOrEmpty(pageRange))
    {
        var parts = pageRange.Split('-');
        if (parts.Length == 2 && 
            int.TryParse(parts[0], out startPage) && 
            int.TryParse(parts[1], out endPage))
        {
            startPage = Math.Max(1, Math.Min(startPage, totalPages));
            endPage = Math.Max(startPage, Math.Min(endPage, totalPages));
        }
    }

    var baseName = Path.GetFileNameWithoutExtension(pdfPath);
    
    await AnsiConsole.Progress()
        .StartAsync(async ctx =>
        {
            var task = ctx.AddTask("拆分 PDF 页面", maxValue: endPage - startPage + 1);

            for (int i = startPage; i <= endPage; i++)
            {
                using var outputDocument = new PdfDocument();
                outputDocument.AddPage(inputDocument.Pages[i - 1]);
                
                var outputPath = Path.Combine(outputDir, $"{baseName}_page_{i:D3}.pdf");
                outputDocument.Save(outputPath);
                
                task.Increment(1);
                await Task.CompletedTask;
            }
        });

    AnsiConsole.MarkupLine($"[green]✅ 拆分完成！已生成 {endPage - startPage + 1} 个文件[/]");
    return 0;
}
catch (Exception ex)
{
    AnsiConsole.MarkupLine($"[red]❌ 错误: {ex.Message}[/]");
    return 1;
}

# 准备测试 PDF 文件
cd split-pdf

# 测试拆分所有页面
dotnet scripts/split-pdf.cs test.pdf ./output/

# 测试拆分指定范围
dotnet scripts/split-pdf.cs test.pdf ./output/ 1-3

# 验证输出
ls ./output/
# 应该看到：test_page_001.pdf, test_page_002.pdf, test_page_003.pdf

# 测试文件不存在
dotnet scripts/split-pdf.cs nonexistent.pdf ./output/

# 测试参数不足
dotnet scripts/split-pdf.cs

# 测试无效页面范围
dotnet scripts/split-pdf.cs test.pdf ./output/ 100-200

用户提问：请帮我把这个 PDF 文件拆分成单独的页面

Agent 行为：
1. 识别任务涉及 PDF 拆分
2. 查找并激活 split-pdf skill
3. 读取 SKILL.md 了解使用方法
4. 执行：dotnet scripts/split-pdf.cs document.pdf ./pages/
5. 向用户报告结果

// ❌ 不好：参数含义不明
dotnet tool.cs input output 1

// ✅ 好：参数含义清晰
dotnet split-pdf.cs document.pdf ./pages/ 1-10

if (args.Length < 2)
{
    AnsiConsole.MarkupLine("[red]错误: 参数不足[/]");
    AnsiConsole.MarkupLine("[yellow]用法: dotnet split-pdf.cs <PDF文件> <输出目录> [页面范围][/]");
    AnsiConsole.MarkupLine("[gray]示例: dotnet split-pdf.cs input.pdf ./output/ 1-5[/]");
    return 1;
}

await AnsiConsole.Progress()
    .StartAsync(async ctx =>
    {
        var task = ctx.AddTask("处理中", maxValue: totalItems);
        foreach (var item in items)
        {
            // 处理逻辑
            task.Increment(1);
        }
    });

// ✅ 指定明确版本
#:package PdfSharpCore@1.3.65
#:package Spectre.Console@0.49.1

// ❌ 避免使用不稳定版本
#:package SomePackage@*
#:package BetaPackage@2.0.0-beta

# ✅ 好的 description
description: Split PDF files into separate single-page documents or extract specific page ranges. Use when you need to divide a PDF into multiple files, extract particular pages, or process PDF pages individually.

# ❌ 不够好
description: PDF tool for splitting.

// ✅ 使用 Path.Combine
var outputPath = Path.Combine(outputDir, $"{baseName}_page_{i:D3}.pdf");

// ❌ 避免硬编码路径分隔符
var outputPath = outputDir + "\\" + baseName + "_page_" + i + ".pdf";

// 确保控制台正确显示 Unicode
Console.OutputEncoding = System.Text.Encoding.UTF8;

pdf-toolkit/
├── SKILL.md
└── scripts/
    ├── split.cs
    ├── merge.cs
    └── extract-text.cs

data-analysis/
├── SKILL.md           # 简要说明和快速开始
├── scripts/
│   └── analyze.cs
└── references/
    ├── REFERENCE.md   # 详细 API 参考
    ├── examples.md    # 更多示例
    └── algorithms.md  # 算法说明

详细的 API 参考请见 [REFERENCE.md](references/REFERENCE.md "REFERENCE.md")。

#:property PublishAot=true
#:property InvariantGlobalization=true  // 减小体积

dotnet publish scripts/tool.cs -r win-x64 --property:PublishAot=true

.github/
└── skills/
    ├── split-pdf/
    ├── data-analysis/
    └── code-review/