CLI Reference

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

Source Content

CLI Reference

Every subcommand and flag for scripts/skill_sync.py. Stdlib only — runs on any Python 3.9+.

Run from the skill directory, or give the full path to the script. Set NO_COLOR=1 to disable ANSI color (already off when output is piped).

list

Show every skill in a source tree with the first sentence of its description.

python3 scripts/skill_sync.py list [--source DIR]

Flags:

• --source DIR — directory of skill folders. Default: ~/.copilot/skills.

validate

Check that skill folders are well-formed and portable. Exits non-zero if any errors are found, so it works as a CI gate.

python3 scripts/skill_sync.py validate <skill-dir>... [--target claude|codex|copilot|generic]

Flags:

• --target — frontmatter dialect to check against. Default: generic. Controls which frontmatter keys are reported as foreign (a warning, not an error).

What it checks:

Check	Severity
SKILL.md present with a valid --- frontmatter block	error
Required keys name and description present	error
name is a valid slug (^[a-z0-9][a-z0-9-]*$, ≤ 64) and equals the folder name	error
description non-empty	error
Relative reference links resolve to an existing file	error
description length under ~1024 chars	warning
Links that resolve but leave the skill folder (sibling/repo refs)	warning
Frontmatter keys foreign to the target dialect	warning
Build/editor junk present (will be skipped on copy)	warning

prompt

Flatten a skill into one self-contained message a person can paste into ChatGPT (or any chat LLM) that has no agent, filesystem, or way to run scripts. Frontmatter becomes a role line, every text reference the skill ships is inlined (all .md/.mdx/.txt, not just the ones SKILL.md links — an unlinked style guide would otherwise be lost), and scripts/data files are listed as “not available in a plain chat.” For reference-heavy skills whose prompt is large, prefer uploading the sync --dir folder to a ChatGPT Custom GPT / Project rather than pasting.

python3 scripts/skill_sync.py prompt <name-or-path> [--source DIR] [--out FILE]

Flags:

• --source DIR — where a bare skill name is resolved. Default: ~/.copilot/skills.
• --out FILE — write to this file instead of stdout.

Reference-heavy skills produce large prompts; the tool prints a size/token warning to stderr when a prompt may exceed a chat’s paste limit.

sync

Validate, then clean-copy skills to one or more destinations. A skill that fails validation for any target dialect is skipped with its errors printed — never partially copied.

python3 scripts/skill_sync.py sync <name-or-path>... \
    [--all] [--to TOOLS] [--dir PATH]... \
    [--tool DIALECT] [--strict] [--force] [--dry-run] [--source DIR]

Selecting skills:

• Positional <name-or-path> — a bare skill name (resolved under --source) or a path to a skill folder. Repeatable.
• --all — every skill in --source. Mutually useful with a single --to.
• --source DIR — where bare names are resolved. Default: ~/.copilot/skills.

Choosing destinations (at least one required):

• --to TOOLS — comma-separated tool names from claude,codex,copilot. Each maps to that tool’s global skills directory.
• --dir PATH — an arbitrary destination folder; the skill lands in <PATH>/<name>/. Repeatable.

Controlling the copy:

• --tool DIALECT — frontmatter dialect for --dir targets. Default: generic.
• --strict — drop frontmatter keys the target dialect does not recognize (e.g. Copilot-only triggers: when syncing to codex). name and description are always kept.
• --prompt — also write <name>.prompt.md (a paste-into-ChatGPT prompt, see the prompt command) into each --dir share. Ignored for --to tool targets, whose agents read SKILL.md directly.
• --force — overwrite an existing destination. Without it, existing destinations are reported as EXISTS and left untouched.
• --dry-run — print planned actions and would-be-stripped keys; write nothing.

Exit codes

Code	Meaning
0	success — all selected skills validated and (for sync) copied
1	one or more skills failed validation, or a usage-level problem occurred
2	argparse usage error (bad flags)

Worked examples

Preview installing every skill into Claude Code, then do it:

python3 scripts/skill_sync.py sync --all --to claude --dry-run
python3 scripts/skill_sync.py sync --all --to claude --force

Share a curated set into a team documentation repo, stripped to the universal core:

python3 scripts/skill_sync.py sync technical-writing markdown docs-that-teach mermaid \
    --dir ~/Code/maryland/documentation --strict

Convert and install a single skill for Codex only:

python3 scripts/skill_sync.py sync agile-product-owner --to codex --strict --force

Validate a skill before committing it to the source repo (CI-style):

python3 scripts/skill_sync.py validate ~/.copilot/skills/skill-sync --target copilot || exit 1