AgentSkillsCN

skills-md

在创建或修改任何技能（全局、项目或包级别）之前，请先使用此技能。它将为您制定严格规范，指导您如何编写紧凑而信息密集的 `SKILL.md` 文件，定义有效的 Frontmatter，并说明何时应将详细信息移至 `references/` 或 `scripts/` 目录。

SKILL.md
--- frontmatter
name: skills-md
description: >
  Use this skill before creating/modifying any skill (global, project, or package-level). It defines hard rules for writing tight, information-dense `SKILL.md` files, valid frontmatter, and when to move details into `references/` or `scripts/`.

Skill authoring rules (mandatory)

Use before any create/edit/move/split of SKILL.md.

Locations

Apply these rules to skills loaded from:

  • •global (source of truth in this setup): ~/.dotfiles/pi/agent/skills/ (synced to ~/.pi/agent/skills/)
  • •project: .pi/skills/
  • •package-provided skill directories
  • •custom paths from settings skills entries or CLI --skill

SKILL.md requirements

  • •Hard cap: 500 tokens max.
  • •Frontmatter must include name and description.
  • •name must match parent directory and use lowercase letters/numbers/hyphens.
  • •description should state when to use the skill, why it exists, and what it covers.
  • •Keep body terse, imperative, and action-oriented.
  • •Put only the default/high-value path in SKILL.md.
  • •Avoid duplicating global guidance or other skills; reference instead.

references/ and scripts/

  • •Use references/*.md for progressive disclosure (edge cases, deep dives, examples, troubleshooting).
  • •Use scripts/ for reusable runnable helpers.
  • •In SKILL.md, explicitly say when to consult a reference or run a script.

Quality gate

Before finishing, verify:

  1. •Common-case execution is possible from SKILL.md alone.
  2. •Every line has operational value (no filler).
  3. •Wording is clear, firm, and unambiguous.

If you changed a skill

Summarize: (1) what changed, (2) why this scope/structure.