AGENT SKILL

skill-gen

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

License 许可
MIT
最近更新
2026-11-10
Stars
★ 0
Forks
0

01 前言 Front Matter

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

03 SKILL.md 正文

<!-- AUTO-GENERATED by skill-gen -- DO NOT EDIT --> <!-- Source: tools/skill-gen/src/index.ts -->

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 (default: .agent/skills/).

Full specification: 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

bun run generate
bun run check
bun run 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

skill-gen/
  SPEC.md               full specification
  src/
    index.ts            Effect CLI entrypoint
    dynamic-fragments.ts optional programmatic fragment sources
    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
  e2e-test/             test input fixtures
  e2e-test-expected/    expected output for e2e comparison

04 同仓库更多 Skills