Encore OS — Documentation

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:

YAML frontmatter delimited by ---
Markdown body with ## System Prompt and optional ## Constraints / ## Examples sections

Example

---
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

Knowledge Base System - Integration Documentation Multi-Site & Multi-NPI Configuration — Integration

Start Here

Module Engineering Snapshots

Canonical AI Governance

Architecture

Integrations

Development

Decision Guides

Database

Module Reference

Testing

Migration

Operations

Governance & Security

Platform Internals

SKILL.md Format and Field Mapping

SKILL.md Format

Example

Field Mapping: SKILL.md ↔ pf_ai_skills

Serializer

Parser

Import Conflict Resolution

Round-Trip Fidelity

References

​SKILL.md Format

​Example

​Field Mapping: SKILL.md ↔ pf_ai_skills

​Serializer

​Parser

​Import Conflict Resolution

​Round-Trip Fidelity

​References

SKILL.md Format

Example

Field Mapping: SKILL.md ↔ pf_ai_skills

Serializer

Parser

Import Conflict Resolution

Round-Trip Fidelity

References