Skill Authoring Guide

Learn how to create, test, and publish your own FPT Digital Foundry 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 FPT Digital Foundry 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": "@phoenix/my-skill",
  "version": "1.0.0",
  "description": "One-sentence skill description",
  "main": "SKILL.md",
  "keywords": ["phoenix-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 @phoenix: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:

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

2. Install the skill by name:

   phoenix 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 #phoenix-skills Teams channel
• Review existing skills in ODCX-Skills/skills/ for reference patterns