dart-expert-skills: Instructions file for GitHub Copilot

Agent Skill Authoring Best Practices

These rules apply whenever creating or updating any SKILL.md file in this repository.

YAML Frontmatter Requirements

Every SKILL.md must begin with valid YAML frontmatter:

---
name: "skill-name-in-gerund-form"
description: "Third-person description of what the skill does and when to use it."
metadata:
  last_modified: "YYYY-MM-DD HH:MM:SS (GMT+8)"
---

name constraints:

• Max 64 characters
• Lowercase letters, numbers, and hyphens only
• Prefer gerund form: processing-pdfs, managing-state, testing-code
• Never: helper, utils, tools, or reserved words (anthropic, claude)

description constraints:

• Max 1024 characters, must be non-empty
• Always write in third person: "Processes Excel files..." not "I can help you..."
• Include both what the skill does and when to use it (specific triggers/contexts)
• Include key terms that enable discovery when 100+ skills are loaded

Conciseness Rules

The context window is shared. Every token in SKILL.md competes with conversation history.

• Assume Claude already knows standard library/framework concepts — do not over-explain
• Challenge every paragraph: "Does Claude need this, or does it already know it?"
• Keep SKILL.md body under 500 lines
• Split long content into separate reference files (e.g., references/ADVANCED.md)

Content Structure

Progressive Disclosure

SKILL.md is the table of contents. Detailed material lives in separate files loaded on demand:

skills/<name>/
  SKILL.md              # metadata + concise overview + links to references
  references/
    REFERENCE.md        # detailed API / schema reference
    EXAMPLES.md         # input-output example pairs
    ADVANCED.md         # edge cases, migration guides, old patterns

• Keep all reference links one level deep from SKILL.md — never nest references inside references
• For reference files over 100 lines, include a table of contents at the top