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

```markdown
---
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.

```markdown
### 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)

```bash
# 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`