Targets and Formats

Field	Value
Type	Skill Resource
Source	~/.copilot/skills/skill-forge/references/targets-and-formats.md
Description	Not specified

Source Content

Targets and Formats

Where each tool expects skills, how their frontmatter differs, and what “converting” a skill really means. Read this when a sync lands in the wrong place or a target tool ignores a skill.

Install locations

Each tool loads personal/global skills from one directory, and keys every skill by its folder name — so the folder name must equal the name: in frontmatter.

Tool	Global skills directory	Notes
Claude Code	~/.claude/skills/<name>/	May not exist yet; the sync script creates it. Project skills also load from <repo>/.claude/skills/.
Codex	~/.codex/skills/<name>/	~/.codex/skills/.system/ holds Codex’s built-in skills — never sync into it.
Copilot	~/.copilot/skills/<name>/	The source of truth for this setup; a real git repo (dmwd-io/.copilot).
Team / project folder	<path>/<name>/	Any folder passed with --dir, e.g. a shared documentation repo.

The one true format

All three tools have converged on the open Agent Skills format, which is why ~/.copilot/skills/technical-writing and ~/.codex/skills/technical-writing are byte-for-byte identical today. A skill is a folder:

<skill-name>/
├── SKILL.md          # required: YAML frontmatter + Markdown body
├── references/       # optional: docs loaded on demand
├── scripts/          # optional: executable helpers
├── assets/           # optional: templates, fonts, images
└── gallery/          # optional: example output

SKILL.md frontmatter must have:

name: <folder-name>          # ^[a-z0-9][a-z0-9-]*$, ≤ 64 chars, equals the folder name
description: <one paragraph> # what it does + when to trigger; keep under ~1024 chars

Because the body and layout are identical across tools, “conversion” is almost never a rewrite of the instructions — it is frontmatter normalization plus a clean copy.

Frontmatter dialects

Extra keys are harmless: a tool ignores frontmatter keys it does not know. So the default is to preserve every key. --strict keeps only the keys the target recognizes.

Claude Code

Recognizes name, description, license, allowed-tools, metadata, compatibility. Uses the description for triggering; does not read a triggers: list.

Codex

Recognizes name, description, license, metadata. Codex’s own skill-creator uses metadata.short-description for a terse label. Does not read triggers:.

Copilot

Recognizes name, description, license, metadata, and a triggers: list of phrases some Copilot skills carry. This is the only dialect that reads triggers:.

Generic (--dir folders)

Defaults to the universal core — name, description, license, metadata. Override with --tool claude|codex|copilot when a --dir copy is destined for a specific tool.

What --strict drops

--strict removes whole top-level frontmatter blocks the target does not recognize, preserving the formatting of every key it keeps (including description: >- block scalars). Examples:

• Syncing a Copilot skill with a triggers: list to codex with --strict → the triggers: block is removed; name + description (+ any metadata/license) remain.
• Syncing to copilot with --strict → triggers: is kept, because Copilot reads it.

name and description are required and never dropped, regardless of dialect.

Junk that is never copied

A clean copy excludes build and editor noise so destinations stay reviewable and teammates never receive machine-specific cruft. Directories: __pycache__, .git, .hg, .svn, .pytest_cache, .mypy_cache, .ruff_cache, .venv, venv, node_modules, .idea, .vscode. Files matching: *.pyc, *.pyo, *.pyd, .DS_Store, *.swp, *.swo, Thumbs.db, *.egg-info, .coverage.

This is the main reason to never hand-copy: ~/.copilot/skills/technical-writing carries a references/mermaid/gallery/build/__pycache__, and a raw cp -r would install it into every teammate’s folder.

Reference-link integrity

validate and sync parse every Markdown link in SKILL.md (ignoring links inside code spans and fenced blocks, which are examples, not real links). Severity depends on whether the link resolves:

• Broken link → error, blocks the sync. The target does not exist relative to the source, so it is broken everywhere. Example: a missing references/catalog.json.
• Escaping link → warning, does not block. The link resolves at the source but points outside the skill folder — a sibling skill (../adr/references/index.md) or the repo root (../../STANDARDS.md). It travels only if its target is synced alongside: fine for a whole-tree tool mirror (--to codex carries every skill), risky for an isolated --dir copy of one skill.

Prefer keeping references inside the skill’s own references/, scripts/, or assets/, so a copy is portable on its own. Cross-skill links are acceptable when you always sync the whole tree.