Skill Authoring Guide

Learn how to create, test, and publish your own ODC-X skills.

What is a Skill?

A skill is a structured markdown file (SKILL.md) containing instructions for an AI assistant. Skills are packaged as npm modules and distributed via the ODC-X registry.

Quick Start

1. Create the Skill Directory

mkdir -p my-skill
cd my-skill

2. Create SKILL.md

---
name: my-skill
description: "One-sentence description of what this skill does and when to invoke it"
metadata:
  author: Your Name
  version: "1.0.0"
  last_updated: "2026-01-01"
  category: code-generation
  tags: "tag1, tag2, tag3"
---

# My Skill Title

## Overview

Explain what this skill does and its core philosophy in 2–3 sentences.

## When to Use

- Bullet points describing trigger conditions
- What user requests should invoke this skill
- Phrases the user might say: "do X", "help me with Y"

## Prerequisites

- What context does the AI need?
- What files or data should be available?

## Instructions

### Step 1: Gather Context
...

### Step 2: Apply the Skill
...

### Step 3: Deliver Output
...

## Output Format

Describe the expected output structure.

## Examples

### Example Input
...

### Example Output
...

3. Create package.json

{
  "name": "@odcx/my-skill",
  "version": "1.0.0",
  "description": "One-sentence skill description",
  "main": "SKILL.md",
  "keywords": ["odcx-skill", "ai", "tag1"],
  "author": "Your Name <your.email@fpt.com>",
  "license": "Internal",
  "publishConfig": {
    "registry": "https://pkgs.dev.azure.com/FPT-Software/_packaging/odcx-skills/npm/registry/"
  }
}

SKILL.md Format Reference

Frontmatter (YAML)

Field	Required	Description
name	✓	Unique kebab-case identifier
description	✓	One-sentence description for marketplace display. Include trigger phrases.
metadata.author	✓	Author full name
metadata.version	✓	Semantic version (e.g., "1.0.0")
metadata.last_updated	✓	ISO date string
metadata.category	✓	One of: code-generation, code-review, architecture, testing, security, devops, planning, documentation, other
metadata.tags	✓	Comma-separated tags for search
license	—	License statement

Required Sections

Every skill should have these sections:

1. Overview — Purpose and philosophy (2–4 sentences)
2. When to Use — Trigger conditions and user intent patterns
3. Prerequisites — Required context and inputs
4. Instructions — Step-by-step execution guide
5. Output Format — Expected deliverables

Optional Sections

• Examples — Sample inputs/outputs
• Related Skills — Cross-references to complementary skills
• Limitations — Known constraints

Writing Effective Instructions

Be Specific

❌ "Analyze the code"
✓ "Read all files in src/ and identify functions longer than 30 lines"

Use Numbered Steps

The AI executes instructions sequentially. Number your steps:

### Step 1: Load Context
Read the file at the provided path.

### Step 2: Apply Analysis
For each function, check:
- Lines of code (flag if > 30)
- Cyclomatic complexity
...

Specify Output Structure

Define exactly what the AI should produce:

## Output Format

Produce a markdown report with:
1. **Summary** — one paragraph overview
2. **Issues Found** — table with columns: File, Line, Severity, Description
3. **Recommendations** — numbered list

Use Conditional Logic

If the codebase uses TypeScript:
  - Check for `any` types
  - Verify strict mode is enabled

If the codebase uses JavaScript:
  - Check for missing JSDoc

Publishing a Skill

Prerequisites

• Azure DevOps account with write access to the odcx-skills feed
• npm authenticated with the feed:

npm config set @odcx:registry https://pkgs.dev.azure.com/FPT-Software/_packaging/odcx-skills/npm/registry/
npm login --registry=https://pkgs.dev.azure.com/FPT-Software/_packaging/odcx-skills/npm/registry/

Publish

npm publish

Versioning

Follow semantic versioning:

• Patch (1.0.1): Typo fixes, minor wording improvements
• Minor (1.1.0): New sections, added instructions, backward-compatible
• Major (2.0.0): Complete restructure, breaking changes to output format

Testing Your Skill

Before publishing, test the skill manually:

1. Add the local skills directory as a source and sync:

   odcx source add test-local --local-path /path/to/ODCX-Skills
   odcx source sync test-local

2. Install the skill by name:

   odcx skill install my-skill

3. Open a project with the relevant context

4. Invoke the skill with your AI assistant:

   Using the my-skill skill, [task description]

5. Verify the output matches the specified format

6. Test edge cases:

   • Empty input
   • Large files
   • Non-standard project structures

Skill Lifecycle

Draft → Review → Published → Deprecated

1. Draft: Work in progress, not yet published
2. Review: Under peer review before publishing
3. Published: Available in the marketplace
4. Deprecated: Superseded by a newer skill; still installable but not recommended

Community Standards

• Keep skills focused on one specific task
• Write instructions that work without additional context
• Include at least 2 concrete examples
• Avoid hard-coding project-specific paths or names
• Prefer descriptive variable names over abbreviations in the instructions

Getting Help

• Open an issue in the ODCX-Skills repository
• Post in the #odcx-skills Teams channel
• Review existing skills in ODCX-Skills/skills/ for reference patterns