第 12 讲Skills、提示模板、主题与 Pi Packages 生态

pdf-tools/
├── SKILL.md
├── scripts/
│   └── extract.sh
├── references/
│   └── formats.md
└── assets/
    └── template.json

---
name: pdf-tools
description: Extract text and tables from PDF files. Use when reading, converting, or inspecting PDFs.
---

# PDF tools

Read `references/formats.md` before converting a document. Run scripts relative to this skill directory.

/** Max name length per spec */
const MAX_NAME_LENGTH = 64;
/** Max description length per spec */
const MAX_DESCRIPTION_LENGTH = 1024;

function validateName(name: string): string[] {
  const errors: string[] = [];
  if (name.length > MAX_NAME_LENGTH)
    errors.push(`name exceeds ${MAX_NAME_LENGTH} characters (${name.length})`);
  if (!/^[a-z0-9-]+$/.test(name))
    errors.push(`name contains invalid characters (must be lowercase a-z, 0-9, hyphens only)`);
  if (name.startsWith("-") || name.endsWith("-"))
    errors.push(`name must not start or end with a hyphen`);
  if (name.includes("--"))
    errors.push(`name must not contain consecutive hyphens`);
  return errors;
}

---
name: github-work
description: Work on GitHub issues and pull requests of this repo. Use when asked to
  investigate, analyze, fix, or review an issue or PR, and when asked to wrap up
  such work (changelog, comment, commit, push, close).
---

# Working on GitHub issues and PRs

The repo's prompt templates in `.pi/prompts/` (two directories above this skill)
define the workflow. Read the matching template in full and follow it.

export function formatSkillsForPrompt(
  skills: Skill[], fileReadTool: "read" | "bash" | "indirect" = "read"
): string {
  const visibleSkills = skills.filter((s) => !s.disableModelInvocation);
  if (visibleSkills.length === 0) return "";

  const lines = [
    "\n\nThe following skills provide specialized instructions for specific tasks.",
    fileReadTool === "read"
      ? "Use the read tool to load a skill's file when the task matches its description."
      : /* bash / indirect 变体，此处省略 */ "",
    "Resolve relative paths against the skill's directory (parent of SKILL.md). Use absolute paths in tool calls.",
    "",
    "<available_skills>",
  ];
  for (const skill of visibleSkills) {
    lines.push("  <skill>");
    lines.push(`    <name>${escapeXml(skill.name)}</name>`);
    lines.push(`    <description>${escapeXml(skill.description)}</description>`);
    lines.push(`    <location>${escapeXml(skill.filePath)}</location>`);
    lines.push("  </skill>");
  }
  lines.push("</available_skills>");
  return lines.join("\n");
}

private _expandSkillCommand(text: string): string {
  if (!text.startsWith("/skill:")) return text;
  const spaceIndex = text.indexOf(" ");
  const skillName = spaceIndex === -1 ? text.slice(7) : text.slice(7, spaceIndex);
  const args = spaceIndex === -1 ? "" : text.slice(spaceIndex + 1).trim();

  const skill = this.resourceLoader.getSkills().skills.find((s) => s.name === skillName);
  if (!skill) return text; // 未知技能，原样传递

  const content = readFileSync(skill.filePath, "utf-8");
  const body = stripFrontmatter(content).trim();
  const skillBlock =
    `<skill name="${skill.name}" location="${skill.filePath}">\n` +
    `References are relative to ${skill.baseDir}.\n\n${body}\n</skill>`;
  return args ? `${skillBlock}\n\n${args}` : skillBlock;
}

function findGitRepoRoot(startDir: string): string | null {
  let dir = resolve(startDir);
  while (true) {
    if (existsSync(join(dir, ".git"))) return dir;
    const parent = dirname(dir);
    if (parent === dir) return null;
    dir = parent;
  }
}

function collectAncestorAgentsSkillDirs(startDir: string): string[] {
  const skillDirs: string[] = [];
  const resolvedStartDir = resolve(startDir);
  const gitRepoRoot = findGitRepoRoot(resolvedStartDir);
  let dir = resolvedStartDir;
  while (true) {
    skillDirs.push(join(dir, ".agents", "skills"));
    if (gitRepoRoot && dir === gitRepoRoot) break;
    const parent = dirname(dir);
    if (parent === dir) break;
    dir = parent;
  }
  return skillDirs;
}

---
description: Review staged git changes
argument-hint: "[focus]"
---
Review the staged changes. Focus on ${1:-correctness, security, and error handling}.

export function expandPromptTemplate(text: string, templates: PromptTemplate[]): string {
  if (!text.startsWith("/")) return text;
  const match = text.match(/^\/([^\s]+)(?:\s+([\s\S]*))?$/);
  if (!match) return text;
  const templateName = match[1];
  const argsString = match[2] ?? "";
  const template = templates.find((t) => t.name === templateName);
  if (template) {
    const args = parseCommandArgs(argsString);
    return substituteArgs(template.content, args);
  }
  return text;
}

{
  "$schema": "https://pi.dev/schemas/theme.schema.json",
  "name": "dark",
  "appearance": "dark",
  "vars": {
    "text": "okhsl(234 3% 89%)",
    "muted": "okhsl(229 6% 67%)",
    "violet": "okhsl(295 50% 67%)",
    "green": "okhsl(159 59% 67%)",
    "red": "okhsl(20 72% 67%)",
    "blueBg": "okhsl(233 41% 24%)"
  },
  "colors": {
    "accent": "violet",
    "border": "okhsl(231 57% 65%)",
    "success": "green",
    "error": "red",
    "warning": "yellow",
    "muted": "muted",
    "text": "text",
    "selectedBg": "blueBg",
    "userMessageBg": "blueBg",
    "userMessageText": "text",
    "toolPendingBg": "okhsl(229 5% 24%)",
    "toolSuccessBg": "okhsl(158 46% 25%)",
    "toolErrorBg": "okhsl(19 54% 25%)",
    "mdLink": "blue",
    "mdCode": "violet"
  }
}

pi install npm:@example/pi-tools@1.0.0
pi install git:github.com/example/pi-tools@v1
pi install ./local-package

pi list                        # 查看已配置的包
pi remove <source>             # 移除一个
pi update --extensions         # 对账式更新包安装
pi -e npm:@example/pi-tools    # 单次试用，不写入设置

export interface PiManifest {
  extensions?: string[];
  skills?: string[];
  prompts?: string[];
  themes?: string[];
  changelogPath?: string;
}

export function readPiManifest(packageJsonPath: string): PiManifest | null {
  try {
    const pkg: unknown = JSON.parse(stripBom(readFileSync(packageJsonPath, "utf-8")));
    if (!isObject(pkg) || !isObject(pkg.pi)) return null;
    const manifest: PiManifest = {};
    for (const field of RESOURCE_FIELDS) {
      const entries = pkg.pi[field];
      if (Array.isArray(entries) && entries.every((e) => typeof e === "string"))
        manifest[field] = entries;
    }
    if (typeof pkg.pi.changelogPath === "string")
      manifest.changelogPath = pkg.pi.changelogPath;
    return manifest;
  } catch { return null; }
}

if (manifest && hasManifestResourceFields(manifest)) {
  for (const resourceType of RESOURCE_TYPES) {
    const entries = manifest[resourceType];
    this.addManifestEntries(entries, packageRoot, resourceType,
      this.getTargetMap(accumulator, resourceType), metadata);
  }
  return true;
}

// 无显式资源清单：回退到约定目录自动发现
let hasAnyDir = false;
for (const resourceType of RESOURCE_TYPES) {
  const dir = join(packageRoot, resourceType);
  if (existsSync(dir)) {
    const files = collectResourceFiles(dir, resourceType);
    for (const f of files)
      this.addResource(this.getTargetMap(accumulator, resourceType), f, metadata, true);
    hasAnyDir = true;
  }
}
return hasAnyDir;

private async installGit(source: GitSource, scope: SourceScope): Promise<void> {
  const targetDir = this.getGitInstallPath(source, scope);
  if (existsSync(targetDir)) { /* 已存在：fetch 并对齐 ref 后返回（省略） */ return; }
  // ...建目录、清理更新标记（省略）
  await this.runCommand("git", ["clone", source.repo, targetDir]);
  if (source.ref) {
    await this.runCommand("git", ["checkout", source.ref], { cwd: targetDir });
  }
  const packageJsonPath = join(targetDir, "package.json");
  if (existsSync(packageJsonPath)) {
    await this.runNpmCommand(this.getGitDependencyInstallArgs(), { cwd: targetDir });
  }
}

{
  "packages": [
    {
      "source": "npm:@example/pi-tools",
      "extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
      "skills": [],
      "prompts": ["prompts/review.md"]
    }
  ]
}