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/descriptionfrontmatter are silently skipped. - Hand-written SKILL.md files (without
AUTO-GENERATEDheader) 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
testing
Testing patterns and best practices.
coding
General coding patterns and conventions.
skill-gen
Use when adding, modifying, generating, checking, or debugging repo-local skill fragments embedded in source code with //<skill-gen> markers.
gen-github-workflow
Use when creating, modifying, generating, checking, or debugging CI workflow fragments embedded in source code with //<gen-github-workflow> markers.
inbox-agents-md
Decides when to create or update nested AGENTS.md, README.md, and CLAUDE.md files in the agentic-inbox monorepo. Use when adding packages/apps/tools, restructuring subtrees, writing agent docs, or when nested subtree docs may be stale or missing.
generated-repo-surfaces
Use when changing generated workflows, OpenAPI artifacts, project-structure blocks, or repo-local skills.