> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SKILL.md Format and Field Mapping

> Based on .cursor/skills and agentskills.io conventions. A SKILL.md file consists of:

**Version:** 1.0\
**Last Updated:** 2026-03-10\
**Status:** ✅ Complete

> Maps the SKILL.md portable format to `pf_ai_skills` columns for the import/export pipeline.

***

## SKILL.md Format

Based on `.cursor/skills` and agentskills.io conventions. A SKILL.md file consists of:

1. **YAML frontmatter** delimited by `---`
2. **Markdown body** with `## System Prompt` and optional `## Constraints` / `## Examples` sections

### Example

```markdown theme={null}
---
name: Policy Reviewer
skill_code: policy_reviewer
description: Reviews organizational policies for compliance
category: compliance
module: gr
model_preference: anthropic/claude-3.5-sonnet
temperature: 0.3
max_tokens: 4096
output_format: text
use_rag: true
rag_source_types: [documents, policies]
rag_match_count: 5
rag_match_threshold: 0.7
tags: [compliance, review, policy]
version: 1.0.0
source: manual
---

## System Prompt

You are an expert policy reviewer specializing in behavioral health compliance...

## Constraints

- Always cite specific regulatory references
- Flag potential HIPAA violations immediately

## Examples

### Input

Review this medication administration policy for OTP compliance.

### Output

**Compliance Assessment:** ...
```

***

## Field Mapping: SKILL.md ↔ pf\_ai\_skills

| SKILL.md Field        | Location    | pf\_ai\_skills Column | Type    | Required | Notes                                                       |
| --------------------- | ----------- | --------------------- | ------- | -------- | ----------------------------------------------------------- |
| `name`                | frontmatter | `name`                | text    | ✅        | Display name                                                |
| `skill_code`          | frontmatter | `skill_code`          | text    | ✅        | Unique per org; validated `^[a-z][a-z0-9_]*$`               |
| `description`         | frontmatter | `description`         | text    | ❌        | Max 500 chars                                               |
| `category`            | frontmatter | `category`            | text    | ✅        | Enum: compliance, housing, hr, finance, operations, general |
| `module`              | frontmatter | `module`              | text    | ❌        | Core module: gr, hr, fa, lo, rh, fm, it, ce                 |
| `model_preference`    | frontmatter | `model_preference`    | text    | ❌        | e.g., `anthropic/claude-3.5-sonnet`                         |
| `temperature`         | frontmatter | `temperature`         | numeric | ❌        | 0.0–2.0; default 0.7                                        |
| `max_tokens`          | frontmatter | `max_tokens`          | integer | ❌        | Default 4096                                                |
| `output_format`       | frontmatter | `output_format`       | text    | ❌        | text, markdown, json, structured                            |
| `use_rag`             | frontmatter | `use_rag`             | boolean | ❌        | Default false                                               |
| `rag_source_types`    | frontmatter | `rag_source_types`    | text\[] | ❌        | Only when `use_rag: true`                                   |
| `rag_match_count`     | frontmatter | `rag_match_count`     | integer | ❌        | Only when `use_rag: true`                                   |
| `rag_match_threshold` | frontmatter | `rag_match_threshold` | numeric | ❌        | Only when `use_rag: true`                                   |
| `tags`                | frontmatter | `tags`                | text\[] | ❌        | Inline YAML array                                           |
| `version`             | frontmatter | `version`             | text    | ❌        | Semver string                                               |
| `source`              | frontmatter | `source`              | text    | ❌        | Set to `import` on import                                   |
| `## System Prompt`    | body        | `system_prompt`       | text    | ✅        | Max 50,000 chars                                            |
| `## Constraints`      | body        | `constraints`         | text\[] | ❌        | Parsed from `- item` list                                   |
| `## Examples`         | body        | `examples`            | jsonb   | ❌        | Parsed from `### Input` / `### Output` pairs                |

***

## Serializer

**Location:** `src/platform/ai/utils/skill-md-serializer.ts`\
**Function:** `skillToSkillMd(skill: AISkill): string`

Produces a valid SKILL.md string from an `AISkill` object. YAML values are escaped when they contain special characters. Arrays use inline flow style `[item1, item2]`.

***

## Parser

**Location:** `src/platform/ai/utils/skill-md-parser.ts`\
**Function:** `parseSkillMd(content: string): ParseSkillMdResult`

Uses regex-based frontmatter extraction (no `gray-matter` dependency). Returns `{ data, errors, warnings }`. Fatal errors (missing frontmatter, missing name) prevent import; warnings (unknown fields) are informational.

***

## Import Conflict Resolution

When importing, if `skill_code` already exists for the current org:

| Resolution  | Behavior                                                               |
| ----------- | ---------------------------------------------------------------------- |
| **Rename**  | Appends `_imported` suffix (or user-edited code) and creates new skill |
| **Replace** | Overwrites existing skill data via `useUpdateAISkill`                  |

**Hook:** `useImportAISkill` at `src/platform/ai/hooks/useImportAISkill.ts`

***

## Round-Trip Fidelity

The serializer and parser are tested for round-trip fidelity: `serialize → parse → compare` preserves all mapped fields. See `tests/unit/platform/ai/skill-md-parser.test.ts` and `tests/unit/platform/ai/skill-md-serializer.test.ts`.

***

## References

* Parent spec: `specs/pf/specs/PF-62-PHASE-2-3-EXPANSION.md`
* Serializer: `src/platform/ai/utils/skill-md-serializer.ts`
* Parser: `src/platform/ai/utils/skill-md-parser.ts`
* Import hook: `src/platform/ai/hooks/useImportAISkill.ts`
* UI: `src/platform/ai/components/ImportSkillDialog.tsx`, `src/platform/ai/components/CreateSkillWizard.tsx`