calorie-counter/.github/copilot-modules/skills-standards.md

Skills use SKILL.md format with YAML frontmatter. One skill per folder. Test before deploy.

Skills Standards - Native Agent Skills

Module: Skills Standards Component: Native VS Code Agent Skills (Layer 4) Load: When creating/editing skills in .github/skills/ Version: 3.0.0 Updated: 2026-04-20

---

Machine Policy

[SKILL_FORMAT]
FORMAT=SKILL.md
STRUCTURE=YAML_frontmatter + Markdown_body
LOCATION=.github/skills/skill-name/SKILL.md
TOKEN_TARGET=<5000_per_skill
DESCRIPTION_LENGTH=~100_tokens
VS_CODE_VERSION=1.109+

---

SKILL.md Format

File Structure

---
name: lowercase-hyphens-only
description: what + when + keywords (1-1024 chars)
license: MIT
compatibility: VS Code 1.109+, Node.js 18+
metadata:
  tier: TIER-0 | TIER-1 | TIER-2 | TIER-3
  category: governance | security | quality | language | testing
  framework-version: "3.0.0"
  author: virsaitis
  version: "1.0.0"
---

# Skill Title

## Overview
## When to Activate
## Standards & Rules
## Consequences
## Procedures
## Examples
## Validation & Testing
## Quick Reference

Frontmatter Requirements (TIER-1)

Field	Required	Format	Example
name	Yes	lowercase-hyphens, 1-64 chars	python-development
description	Yes	plain text, 1-1024 chars	What + When + Keywords
license	No	SPDX identifier	MIT
compatibility	No	version requirements	VS Code 1.109+
metadata.tier	Yes (Virsaitis)	TIER-0 through TIER-3	TIER-1
metadata.category	Yes (Virsaitis)	governance/security/quality/language/testing	governance

Name MUST match directory name exactly.

Description MUST include: what the skill does, when to activate, discovery keywords.

---

Required Sections

Overview

What this skill does and why. Use atomic sentences. 2-3 paragraphs.

When to Activate

Keywords and scenarios for VS Code skill activation. Include keyword list for discovery.

Standards & Rules

Specific rules grouped by TIER level. Each rule: Name, TIER, Enforcement, Rationale.

Consequences (Virsaitis Extension)

Impact chains per TIER violation. Five dimensions: Operation, User, Technical, Business, Remediation.

### TIER-0 Violations
**Rule**: [Rule Name]
**If Violated**:
- **Operation**: BLOCKED immediately
- **User Impact**: [effect on user]
- **Technical Impact**: [what breaks]
- **Business Impact**: [why it matters]
- **Remediation**: [how to fix]

Procedures

Step-by-step workflows with commands and expected outcomes.

Examples

Good vs Bad code snippets with compliance explanations.

Validation & Testing

Commands to verify compliance, expected output, error interpretation.

Quick Reference

Summary table for rapid lookup.

---

Directory Structure

.github/skills/
├── skill-name/
│   ├── SKILL.md          (required - main skill file)
│   ├── scripts/          (optional - helper scripts)
│   ├── references/       (optional - reference docs)
│   └── assets/           (optional - images, examples)

---

Validation (TIER-1)

# Validate skill structure
skills-ref validate .github/skills/skill-name/

# Expected output:
# ✓ Skill name matches directory
# ✓ Description within 1-1024 chars
# ✓ Frontmatter valid YAML
# ✓ SKILL.md found

Fix all errors before committing.

---

Token Efficiency (TIER-2)

Targets:

• Description: ~100 tokens (efficient discovery)
• Full skill body: <5000 tokens (~500 lines)
• Total loaded: <1% of 200K context window

VS Code loads skills in 3 levels:

1. Metadata (~100 tokens): Always loaded for discovery
2. Instructions (<5000 tokens): Loaded when skill activated
3. Resources (on-demand): Loaded only when referenced

Keep SKILL.md lean. Put large examples in references/.

---

Skill Development Workflow

Create New Skill

1. Choose skill name (lowercase-hyphens)
2. Create directory: .github/skills/skill-name/
3. Fill frontmatter (name must match directory)
4. Write sections: Overview → Rules → Consequences → Procedures
5. Add good/bad examples
6. Validate: skills-ref validate
7. Test activation in VS Code 1.109+
8. Update CHANGELOG and commit

Modify Existing Skill

1. Read current SKILL.md fully
2. Maintain atomic sentence structure
3. Update version in frontmatter
4. Validate and test before commit

---

Quick Reference

Aspect	Standard	Tool
Format	SKILL.md	VS Code markdown
Location	.github/skills/	Repository root
Frontmatter	YAML	--- delimiters
Tokens	<5000 body	Word count estimate
Validation	skills-ref	skills-ref validate
VS Code	1.109+	Check release

---

Skills Standards Module v3.0.0 Native VS Code Agent Skills for Virsaitis governance

---

Key Rules From This Module

• SKILL.md is the entry point. YAML frontmatter with description is required.
• One skill per folder. Folder name matches skill purpose.
• Test every skill before deployment. Manual validation required.
• Skills in .github/skills/ are the one exception to .github write restrictions.
• Definitions: .github/virsaitis-definition-library.md

Return to hub: .github/copilot-instructions.md