Menu
Use when adding, modifying, generating, checking, or debugging repo-local skill fragments embedded in source code with //<skill-gen> markers.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Create small, atomic, Conventional Commits. Use when the user asks to commit, split work into commits, draft commit messages, or stage related changes — never for drive-by mega-commits.
Use when designing Effect HTTP API surfaces (HttpApi, HttpApiClient, branded params, typed errors), Effect Config / AppConfig, module boundaries (Domain/Errors/Api/Service/Repo), sub-modules, Postgres persistence, or reviewing backend layout in apps/api or packages/api-core. Prefer repos/effect-smol and docs/agent-patterns/ for Effect idioms. NOT for visual UI.
Use when changing generated workflows, OpenAPI artifacts, project-structure blocks, or repo-local skills.
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.
Use when creating, modifying, generating, checking, or debugging CI workflow fragments embedded in source code with //<gen-github-workflow> markers.
Use when adding, modifying, generating, checking, or debugging repo-local skill fragments embedded in source code with //<skill-gen> markers.
| name | skill-gen |
| description | Use when adding, modifying, generating, checking, or debugging repo-local skill fragments embedded in source code with //<skill-gen> markers. |
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
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.paths: is preserved in generated output.// or #) are stripped automatically.| 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.
bun run generate
bun run check
bun run e2e-test
| 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) |
name/description frontmatter are silently skipped.AUTO-GENERATED header) are never overwritten.references/ subdirectory is not managed by skill-gen -- those remain hand-written.<!-- AUTO-GENERATED by skill-gen -- DO NOT EDIT --> header with source file paths.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