feat(cli): skillforge format <path> reformats SKILL.md to canonical shape

[adityachilka1]

What

skillforge format <path> — reformat a SKILL.md to canonical shape. Seventh piece of the authoring workflow after init, validate, lint, pack, install, and update. Think prettier for the SKILL.md envelope: lint flags style smells, format fixes them.

# Format in place (default)
skillforge format ./code-review/SKILL.md
# ✓ formatted ./code-review/SKILL.md

# CI mode — exit 1 if anything would change
skillforge format ./code-review/SKILL.md --check

# Preview without writing
skillforge format ./code-review/SKILL.md --dry-run
# dry-run ./code-review/SKILL.md (nothing written)

# Print to stdout instead of writing
skillforge format ./code-review/SKILL.md --write=false

Semantics

Aspect	Behaviour
Frontmatter key order	Schema declaration order: name, description, version, tags, author, homepage
Passthrough (unknown) keys	Preserved, alphabetized, at the end
Stringy primitives	tags: "[]" → tags: [] (coerced back to YAML primitives)
Multi-line strings	Emitted as `
Trailing whitespace	Stripped from every frontmatter and body line
Blank-line runs (body)	3+ consecutive blanks collapsed to exactly 2
Trailing newline	Exactly one at EOF
Fenced code blocks (```)	Preserved verbatim — no whitespace touched inside
Already-canonical input	changed: false, no write, exit 0
Schema-invalid output	Refuses to write, file untouched, exit 1

Body preservation

Unlike update, format does re-emit the frontmatter envelope — that's the whole point. But the body is treated gently: we trim trailing whitespace per line, collapse blank-line runs, and ensure a single EOF newline. Fenced code blocks are byte-verbatim (test asserts that trailing-space and 4-blank-line runs inside a python block survive untouched), and prose is never reflowed.

Idempotence

Hard requirement, hard tested: a dedicated test runs format twice on a deliberately scrambled file (out-of-order frontmatter, passthrough keys, trailing whitespace, blank-line runs, code block) and asserts the second run is byte-identical to the first, with changed: false.

--check flag

Alias for --dry-run that exits 1 if the file would change. Drops into CI:

- run: npx @adityachilka/skillforge format ./skills/*.md --check

Validation

The formatted frontmatter is run through SkillFrontmatterSchema before anything hits disk. A description under 20 chars or a malformed version string causes format to exit 1 with the schema error — the file is left untouched, never a half-written invalid SKILL.md on disk.

Exit codes

Situation	Exit
Successful format / dry-run / already-canonical	0
--check and the file would change	1
Any failure (missing file, no frontmatter, schema fail)	1

Same posture as init/validate/pack/install/lint/update.

Surface

• src/format.ts — formatSkill() plus the canonical YAML emitter and body normalizer. ~340 LOC. No new runtime deps; reuses gray-matter for parsing, hand-written emitter.
• src/format.test.ts — 17 tests covering frontmatter reordering, passthrough alphabetization, stringy tags coercion, trailing-whitespace stripping, blank-line collapse, trailing-newline normalization (add + collapse), code-block verbatim preservation, dry-run, --write=false, idempotence, no-op on canonical input, schema refusal, missing file, dir-without-SKILL.md, dir resolution, no-frontmatter rejection.
• src/cli.ts — new format subcommand with --write, --dry-run, --check.
• src/index.ts — re-exports formatSkill, FormatOptions, FormatResult.
• README.md — new ### skillforge format <path> section; status line updated.
• CHANGELOG.md — Unreleased entry (no version-section migration; that's a release-prep PR).

Gates

Check	Status
pnpm typecheck (tsc --noEmit)	clean
pnpm lint (biome)	clean
pnpm test (vitest)	101/101 pass (17 new + 84 existing)
pnpm build (tsup)	ESM + DTS build success
Smoke: ./dist/cli.js format … --check on scrambled input	exit 1 (would-change)
Smoke: ./dist/cli.js format …	✓ formatted …, exit 0
Smoke: ./dist/cli.js format … --check after format	exit 0 (already canonical) — idempotence proven

On format vs lint

lint surfaces trailing-whitespace as a warning. format fixes it. They compose: run format to fix the auto-fixable, then lint for the residual semantic smells (description-no-trigger, missing-when-to-use, etc.) that need human judgment.

Declaration of AI-Tools / LLMs usage

• Claude (Opus) for design, implementation, tests, commit message, this PR body — reviewed by @adityachilka1 before push.

[coderabbitai]

Warning

Review limit reached

@adityachilka1, we couldn't start this review because you've used your available PR reviews for now.

Your plan currently allows 1 review/hour. Refill in 35 minutes and 36 seconds.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more review capacity refills, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than trial, open-source, and free plans. In all cases, review capacity refills continuously over time.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f93b85fd-f784-444d-9a71-e36b073e55b2

📥 Commits

Reviewing files that changed from the base of the PR and between acbd282 and c204863.

📒 Files selected for processing (6)

• CHANGELOG.md
• README.md
• src/cli.ts
• src/format.test.ts
• src/format.ts
• src/index.ts

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/format

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}