skill-gen

name	skill-gen
description	Use when adding, modifying, generating, checking, or debugging repo-local skill fragments embedded in source code with //<skill-gen> markers.

skill-gen

Scans source files for //<skill-gen> markers, extracts skill fragments (markdown with YAML frontmatter), merges them by skill name, and writes SKILL.md files to the configured output folder. Pawrrtal's canonical output is .agent/skills/ (agentic-stack brain); .agents/skills/ and .cursor/plugins/pawrrtal/skills/ mirror it.

Full specification: packages/ci/skill-gen/SPEC.md

Quick Reference

Fragment Format

Embed skill fragments in any source file using comment markers:

//<skill-gen>
// ---
// name: my-skill
// description: "What this skill teaches agents."
// ---
//
// ## Section Heading
//
// Markdown body content here.
//</skill-gen>

• name (required): identifies which skill this fragment belongs to. Fragments sharing the same name are merged.
• description (required): used in the generated SKILL.md frontmatter.
• Extra frontmatter such as paths: is preserved in generated output.
• Comment prefixes (// or #) are stripped automatically.

Template Variables

Variable	Expands to
$$file	Relative path from repo root to the source file
$$directory	Relative path from repo root to the source file's directory

Use \$$ to produce a literal $$file / $$directory in the output.

CLI Commands

# Generate skill files from source fragments
bun run skill-gen:generate

# Check if generated skills are up-to-date (CI mode)
bun run skill-gen:check

# Run e2e tests against fixtures
bun run skill-gen:e2e-test

Merge Rules

Field	Strategy
name	Must match (merge key)
description	Last writer wins (warns if different)
extra frontmatter	Later non-empty declarations win (warns if different)
body	Concatenated in source-file order (sorted by relative path)

Key Behaviors

• Fragments without valid name/description frontmatter are silently skipped.
• Hand-written SKILL.md files (without AUTO-GENERATED header) are never overwritten.
• The references/ subdirectory is not managed by skill-gen -- those remain hand-written.
• Output files include <!-- AUTO-GENERATED by skill-gen -- DO NOT EDIT --> header with source file paths.

Project Layout

packages/ci/skill-gen/
  SPEC.md               full specification
  src/
    index.ts            Effect v4 CLI entrypoint
    scan.ts             file tree walker + fragment extractor
    parse.ts            comment stripping + frontmatter parsing
    merge.ts            merge logic (concatenate bodies)
    output.ts           write / diff output files
    e2e.ts              e2e fixture comparison (collect/compare SKILL.md files)
  e2e-test/             test input fixtures
  e2e-test-expected/    expected output for e2e comparison