# SKILL.md Extended Schema

GMD extends the [agentskills.io](https://agentskills.io/specification) SKILL.md format with additional fields for behavioral enforcement, discovery, and categorization. The agentskills.io spec requires only `name` and `description`; custom fields are allowed by the spec.

## Field Tiers

### Required (ALL skills)

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Unique skill identifier (kebab-case). Used by the Skill tool for invocation. |
| `description` | string (`>-` for multi-line) | When to use this skill. Discovery-facing -- keep concise. |
| `type` | enum | `behavioral` -- enforces discipline with trigger patterns. `utility` -- provides tools/workflows on demand. `reference` -- passive knowledge base. |

### Behavioral-Only Required (when `type: behavioral`)

| Field | Type | Description |
|-------|------|-------------|
| `trigger-patterns` | list of strings | Task contexts that should activate this skill. First 3 shown in discovery index. |
| `discipline` | enum | `rigid` -- iron law, no exceptions; must co-invoke `rationalization-prevention`. `flexible` -- guidelines, agent discretion. |

### Recommended / Optional (any skill)

| Field | Type | Description |
|-------|------|-------------|
| `allowed-tools` | list | Claude Code tools this skill may use. |
| `category` | string | Grouping label (e.g., `security`, `development`, `orchestration`). |
| `tags` | list | Search/filter keywords. |
| `version` | semver string | Skill version (e.g., `"1.0.0"`). |
| `requires` | list | Other skill names that must be loaded first. |
| `agents` | list | Agent classes this skill targets. Empty = all agents. |

## Two-Layer Rationalization Rule

Skills with `discipline: rigid` must be invoked alongside the `rationalization-prevention` skill. This is enforced by the `using-gmd` master skill:

1. Agent reads the skill index at session start.
2. When a rigid skill is invoked via the Skill tool, the agent also invokes `rationalization-prevention`.
3. The central `rationalization-prevention` skill provides universal anti-discipline patterns.
4. Each rigid skill adds its own domain-specific rationalization table in its body.

This creates two-layer defense: central patterns (immune system baseline) + domain extensions (targeted antibodies).

## Behavioral Skill Example

```yaml
---
name: test-driven-development
description: >-
  Use when implementing any feature or bugfix, before writing implementation code.
  Enforces strict red-green-refactor discipline with iron law.
type: behavioral
trigger-patterns:
  - implementing features
  - writing new code
  - fixing bugs
  - refactoring
discipline: rigid
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
category: development
tags: [tdd, testing, red-green-refactor]
version: "1.0.0"
agents:
  - gmd-executor
  - gmd-debugger
---

# Test-Driven Development (TDD)

## The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

[... skill body with enforcement rules, red-green-refactor process,
and domain-specific rationalization prevention table ...]
```

## Utility Skill Example

```yaml
---
name: codeql
description: >-
  Scans a codebase for security vulnerabilities using CodeQL's interprocedural
  data flow and taint tracking analysis.
type: utility
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
  - Glob
  - Grep
category: security
tags: [codeql, sast, vulnerability-scanning]
---

# CodeQL Analysis

[... skill body with workflows, references, usage instructions ...]
```

## Notes

- The `description` field is for discovery (WHEN to use). Behavioral enforcement goes in the SKILL.md body (HOW to behave).
- Skills imported from external sources without `type` default to `utility`.
- The compact skill index (~50 tokens per skill) shows `name`, `type`, `discipline`, and up to 3 trigger patterns. Full content is loaded on-demand via the Skill tool.
