sensei copilot-instructions.md

Copilot Instructions

Follow AGENTS.md as the canonical contributor guidance for this repository. This file summarizes the highest-impact rules for GitHub Copilot and Copilot Coding Agent.

Project Context

This repository is Sensei, an Agent Skill that improves SKILL.md frontmatter compliance. The root SKILL.md is the runtime skill; README.md is human-facing documentation; references/ contains progressive-disclosure docs; scripts/ contains the TypeScript token/scoring CLI and optional GEPA evaluator.

Skill Authoring Rules

• Keep SKILL.md focused on operational instructions, not README-style documentation.

• Put detailed explanations, examples, and templates under references/.

• Preserve Agent Skills frontmatter format:

  ---
  name: skill-name
  description: "**WORKFLOW SKILL** - What the skill does. WHEN: \"trigger 1\", \"trigger 2\", \"trigger 3\". INVOKES: tools used. FOR SINGLE OPERATIONS: when to bypass."
  ---
  

• Prefer positive routing with WHEN: / USE FOR: trigger phrases.

• Avoid DO NOT USE FOR: in descriptions because it can contaminate skill routing.

• Keep description fields under 1024 characters.

• Use inline double-quoted descriptions, not folded YAML scalars.

• Use skill type prefixes consistently: **WORKFLOW SKILL**, **UTILITY SKILL**, or **ANALYSIS SKILL**.

Token and Scoring Expectations

• Target SKILL.md at about 500 tokens; hard limit is 5000 tokens.
• Keep references/*.md near 2000 tokens or less.
• Target Medium-High or High advisory score:
  • Medium-High: trigger phrases with a concise description.
  • High: Medium-High plus routing clarity such as INVOKES: and FOR SINGLE OPERATIONS:.

Validation Commands

Run the narrowest relevant checks after changes:

npm run tokens -- check [paths...]
npm run tokens -- score .
npm test

Use npm run tokens -- count [paths...], npm run tokens -- suggest [paths...], or npm run tokens -- compare [refs...] when working on token budgets or optimization.