# Skill Gen

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

- Skill: `octaviantocan/skill-gen` (Agent Skill)
- Install (CLI): `npx skillmds@latest add octaviantocan/skill-gen`
- Raw SKILL.md: https://api.skillmd.com/api/skills/octaviantocan/skill-gen/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: octaviantocan (https://skillmd.com/u/octaviantocan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/octaviantocan/skill-gen

---


<!-- AUTO-GENERATED by skill-gen -- DO NOT EDIT -->
<!-- Source: packages/ci/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. 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:

```ts
//<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

```bash
# 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
```