Universal Skill Anatomy

Every skill across all MAGIC suites follows the same SKILL.md structure, making skills portable, parseable, and consistent.

SKILL.md Structure

A SKILL.md file is the authoritative definition of a skill. AI coding assistants read this file to understand what a skill does, when to invoke it, and how to use it.

---
name: skill-name
description: One-line description used for skill selection
metadata:
  type: skill
  domain: data-science | nlp | devops | ...
  triggers: ["keyword1", "keyword2"]
---

## Overview
What this skill does and when to use it.

## Usage
How to invoke the skill and what to expect.

## Parameters
Key inputs and their types.

## Examples
Concrete invocation examples with expected output.

## Acceptance Criteria
How to verify the skill worked correctly.

Key Fields

Frontmatter

• name — kebab-case identifier, unique within a suite
• description — one-line summary used by AI tools for skill selection
• metadata.type — always skill for skill files
• metadata.domain — the knowledge domain this skill encodes
• metadata.triggers — keywords that activate automatic skill invocation

Body Sections

• Overview — non-obvious context about what the skill does and why
• Usage — invocation pattern, including required context
• Parameters — typed inputs the skill consumes
• Examples — real invocation examples, not synthetic demos
• Acceptance Criteria — verifiable checks that the skill succeeded

Design Principles

• Skills encode workflow knowledge, not just code snippets
• Acceptance criteria make skills testable
• Triggers enable automatic invocation by AI tools
• Domain metadata enables cross-suite skill discovery