Skip to content

skill-conventions.md

Latest commit

 

History

History
81 lines (59 loc) · 2.6 KB

skill-conventions.md

File metadata and controls

81 lines (59 loc) · 2.6 KB

Skill File Conventions

Detailed guidelines for writing and maintaining agent skills in Skill Matrix.

File Naming

Prefix Category Example
web- Web integration (Vanilla, React, Angular) web-react-setup.md
native- Native iOS/Android native-android-setup.md
cross- Cross-platform (React Native, Flutter) cross-react-native-setup.md
sdk- SDK development internals sdk-rescript-bindings.md
build- Build tools and pipelines build-multi-platform.md

Use lowercase, hyphen-separated names that describe the action or topic.

YAML Frontmatter

Required fields for reference files:

---
title: Human-readable title
impact: CRITICAL | HIGH | MEDIUM
tags: comma, separated, searchable, keywords
---

Section Order

  1. Quick Pattern / Quick Command / Quick Config / Quick Reference — Choose one based on skill type
  2. When to Use — Conditions that trigger this skill
  3. Prerequisites — Required tools, versions, setup
  4. Step-by-Step Instructions — Numbered, actionable steps
  5. Code Examples — Before/after patterns
  6. Common Pitfalls — What to avoid
  7. Related Skills — Links to complementary skills

Quick Section Types

Type Use When Example
Quick Pattern Code transformation Incorrect -> Correct code
Quick Command Shell/tool invocation npx hyperswitch-setup
Quick Config Configuration change SDK initialization snippet
Quick Reference Conceptual overview Summary table

Writing Style

  • Imperative voice: "Run this command" not "You should run this command"
  • Scannable: Bullet points over paragraphs
  • Specific: Include version numbers, exact commands
  • Testable: Every instruction should be verifiable

Linking

Use relative paths for internal links:

See [web setup](./web-react-setup.md) for React integration.

Maintain bidirectional links in Related Skills sections.

Impact Ratings

Rating Meaning User Action
CRITICAL Required for SDK to function Must implement
HIGH Significant improvement to integration Prioritize
MEDIUM Recommended best practice Address when possible

SKILL.md Structure

The main SKILL.md file should contain:

  1. YAML frontmatter with name, description, license, metadata
  2. Overview — What the skill covers
  3. When to Apply — Trigger conditions
  4. Quick Reference — Table linking to reference files
  5. Problem -> Skill Mapping — Symptom to solution lookup