What is the purpose of SKILL.md frontmatter in a skill?

Frontmatter defines the skill metadata (e.g., name, description) and enables consistent tooling; it must be valid and include required fields per the skill-frontmatter guidelines.

How do I validate a skill's structure and frontmatter?

Use the Structure validator script and Frontmatter checker to ensure directory structure and frontmatter meet the guidelines.

Where can I find templates and references for building skills?

Templates and references are located under assets/templates and referenced guidelines under references within the SKILL.md workflow, with links to progressive disclosure and design patterns.

implement-agent-skills

npx machina-cli add skill yu-iskw/google-cloud-observability-plugin/implement-agent-skills --openclaw

Files (1)

SKILL.md

2.4 KB

Implement Agent Skills

Create or update skills/<skill-name>/SKILL.md files with deterministic scope and reusable references/scripts/templates.

Workflow

Assess complexity: Use decision framework to determine skill level needed (simple vs workflow)
Start simple: Choose simplest skill type that meets requirements
Define scope: Single-purpose objective with clear trigger criteria and success metrics
Create/update: skills/<name>/SKILL.md with valid frontmatter
Add supporting materials: References/scripts/templates for progressive disclosure
Plan evaluations: Identify 20-50 test cases to validate skill behavior
Validate: Check frontmatter and directory structure
Cross-link: Connect to plugin packaging or umbrella guidance as needed

Progressive Disclosure

Best Practices (Anthropic Guidelines)

Complexity decision framework: ../implement-claude-extensions/references/decision-framework.md
Context management patterns: ../implement-claude-extensions/references/context-management.md
Evaluation strategy: ../implement-claude-extensions/references/evaluation-strategy.md

Skill Design Patterns

Skill directory conventions: references/skill-structure.md
Required frontmatter fields: references/skill-frontmatter.md
Progressive disclosure patterns: references/skill-progressive-disclosure.md
Invocation and trigger guidance: references/skill-invocation.md

Validation Tools

Structure validator: scripts/validate-skill-structure.sh
Frontmatter checker: scripts/check-skill-frontmatter.sh

Tiered Templates (by Complexity)

Level 1 - Simple Skill (Score 1-3): assets/templates/skill-simple.md
Level 2 - Workflow Skill (Score 4-6): assets/templates/skill-workflow.md
Base skill template: assets/templates/skill-template.md
Skill with references example: assets/templates/skill-with-references.md
Skill with scripts example: assets/templates/skill-with-scripts.md

Related Skills

Umbrella routing and component selection: ../implement-claude-extensions/SKILL.md
Plugin packaging/distribution: ../implement-plugin/SKILL.md

Sources

Source

git clone https://github.com/yu-iskw/google-cloud-observability-plugin/blob/main/.claude/skills/implement-agent-skills/SKILL.md

View on GitHub

Overview

This skill guides creating or updating skills/<skill-name>/SKILL.md with deterministic scope, reusable references and progressive disclosure. It covers the workflow from assessing complexity to cross-linking with umbrella guidance and tooling.

How This Skill Works

Technically, you assess complexity using a decision framework and start with the simplest skill type. Then you create/update skills/<name>/SKILL.md with valid frontmatter, add supporting materials for progressive disclosure, and plan 20-50 test cases to validate behavior. Finally, you validate the structure and frontmatter and cross-link to umbrella guidance or packaging as needed.

When to Use It

When starting a new Claude Agent Skill from scratch and you need a clear frontmatter-backed definition.
When refining an existing skill to fit a workflow pattern (Level 2) using the tiered templates.
When adding references/scripts/templates to support progressive disclosure.
When performing validation of skill structure and frontmatter with the provided tools.
When wiring the skill into umbrella guidance or plugin packaging for deployment.

Quick Start

Step 1: Assess complexity and select Level 1 or Level 2 template using the decision framework.
Step 2: Create/update skills/<name>/SKILL.md with valid frontmatter and core objective.
Step 3: Add references/templates, plan 20-50 tests, validate structure/frontmatter, and cross-link as needed.

Best Practices

Use the complexity decision framework to choose Level 1 (simple) or Level 2 (workflow) appropriately.
Keep the scope single-purpose with clear trigger criteria and measurable success metrics.
Always create or update SKILL.md with valid frontmatter and deterministic scope.
Prepare 20-50 test cases to thoroughly validate skill behavior before release.
Leverage tiered templates and reference materials for progressive disclosure and consistency.

Example Use Cases

Create a Level 1 Simple Skill using assets/templates/skill-simple.md for a greeting agent.
Develop a Level 2 Workflow Skill guided by assets/templates/skill-workflow.md for data retrieval.
Use the base template assets/templates/skill-template.md to craft a new Skill with core structure.
Build a Skill with references using assets/templates/skill-with-references.md to demonstrate progressive disclosure.
Create a Skill with scripts using assets/templates/skill-with-scripts.md to show executable templates.

Frequently Asked Questions

Add this skill to your agents