PromptScript API

Class: GitHubFormatter¶

Defined in: formatters/src/formatters/github.ts:219

Formatter for GitHub Copilot instructions.

Supports three versions: - simple: Single .github/copilot-instructions.md file - multifile: Main + .github/instructions/*.instructions.md + .github/prompts/*.prompt.md - full (default): Multifile + .github/skills/<name>/SKILL.md + AGENTS.md

Example¶

targets:
  - github  # uses full mode (default)
  - github:
      version: multifile
  - github:
      version: full

See¶

https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot

Extends¶

• BaseFormatter

Constructors¶

Constructor¶

new GitHubFormatter(): GitHubFormatter

Returns¶

GitHubFormatter

Inherited from¶

BaseFormatter.constructor

Properties¶

defaultConvention¶

readonly defaultConvention: "markdown" = 'markdown'

Defined in: formatters/src/formatters/github.ts:223

Default convention for this formatter

Overrides¶

BaseFormatter.defaultConvention

description¶

readonly description: "GitHub Copilot instructions (Markdown)" = 'GitHub Copilot instructions (Markdown)'

Defined in: formatters/src/formatters/github.ts:222

Human-readable description

Overrides¶

BaseFormatter.description

name¶

readonly name: "github" = 'github'

Defined in: formatters/src/formatters/github.ts:220

Unique formatter identifier

Overrides¶

BaseFormatter.name

outputPath¶

readonly outputPath: ".github/copilot-instructions.md" = '.github/copilot-instructions.md'

Defined in: formatters/src/formatters/github.ts:221

Default output file path

Overrides¶

BaseFormatter.outputPath

standardsExtractor¶

protected readonly standardsExtractor: StandardsExtractor

Defined in: formatters/src/base-formatter.ts:47

Shared standards extractor for consistent extraction across all formatters.

Inherited from¶

BaseFormatter.standardsExtractor

CONTEXT_RENDERED_KEYS¶

protected readonly static CONTEXT_RENDERED_KEYS: ReadonlySet\<string>

Defined in: formatters/src/base-formatter.ts:256

@context keys that already have a dedicated rendering path. Anything outside this set is generic and must be surfaced by the context section.

Inherited from¶

BaseFormatter.CONTEXT_RENDERED_KEYS

Methods¶

appendGenericStandardItems()¶

protected appendGenericStandardItems(items, props, knownKeys): void

Defined in: formatters/src/base-formatter.ts:375

Append generic Label: value items for standards keys not handled by the known-key rendering in a section method. Keeps custom

Parameters¶

items¶

string[]

props¶

Record\<string, Value>

knownKeys¶

ReadonlySet\<string>

Returns¶

void

Standards¶

keys (git/config/documentation/diagrams) visible in monolith output. Skips null/undefined/false; renders bare labels for true.

Inherited from¶

BaseFormatter.appendGenericStandardItems

contextArchitectureProperty()¶

protected contextArchitectureProperty(ast): string | null

Defined in: formatters/src/base-formatter.ts:276

Read the architecture property of @context. Used as a fallback for sources that declare architecture as a property rather than as an ## Architecture heading inside the block text.

Parameters¶

ast¶

Program

Returns¶

string | null

Inherited from¶

BaseFormatter.contextArchitectureProperty

contextPropertyItems()¶

protected contextPropertyItems(ast, alsoRenderedKeys?): string[]

Defined in: formatters/src/base-formatter.ts:289

Render @context properties that no dedicated section consumes as Label: value items, so structured context is never silently dropped.

Parameters¶

ast¶

Program

alsoRenderedKeys?¶

readonly string[] = []

Returns¶

string[]

Inherited from¶

BaseFormatter.contextPropertyItems

createRenderer()¶

protected createRenderer(options?): ConventionRenderer

Defined in: formatters/src/base-formatter.ts:53

Create a convention renderer for this formatter. Uses the provided convention from options or falls back to the default.

Parameters¶

options?¶

FormatOptions

Returns¶

ConventionRenderer

Inherited from¶

BaseFormatter.createRenderer

dedent()¶

protected dedent(text): string

Defined in: formatters/src/base-formatter.ts:685

Remove common leading whitespace from all lines (dedent). Handles the case where trim() was already called, causing the first line to lose its indentation while subsequent lines retain theirs. Calculates minimum indent from lines 2+ only.

Parameters¶

text¶

string

Returns¶

string

Inherited from¶

BaseFormatter.dedent

documentationItem()¶

protected documentationItem(value, defaultText): string | null

Defined in: formatters/src/base-formatter.ts:360

Resolve a documentation-standard entry that accepts either a boolean flag or author-supplied prose. A string value is authoritative and replaces the target's default phrasing, so authored text is never silently discarded.

Parameters¶

value¶

Value | undefined

defaultText¶

string

Returns¶

string | null

Inherited from¶

BaseFormatter.documentationItem

extractContextTechStackItems()¶

protected extractContextTechStackItems(props): string[]

Defined in: formatters/src/base-formatter.ts:322

Collect @context tech-stack entries from every supported shape: an explicit techStack list plus the languages/runtime/monorepo properties.

Parameters¶

props¶

Record\<string, Value>

Returns¶

string[]

Inherited from¶

BaseFormatter.extractContextTechStackItems

extractExamples()¶

protected extractExamples(ast): object[]

Defined in: formatters/src/base-formatter.ts:854

Extract examples from the

Parameters¶

ast¶

Program

Returns¶

object[]

Examples¶

block. Returns an array of example definitions with name, input, output, and optional description.

Inherited from¶

BaseFormatter.extractExamples

extractSectionWithCodeBlock()¶

protected extractSectionWithCodeBlock(text, header): string | null

Defined in: formatters/src/base-formatter.ts:409

Safe extraction of a section that contains a header + content + code block + content Avoids ReDoS by using string search instead of backtracking regex. Matches pattern: Header ... ...

Parameters¶

text¶

string

header¶

string

Returns¶

string | null

Inherited from¶

BaseFormatter.extractSectionWithCodeBlock

extractSkillExamples()¶

protected extractSkillExamples(skillProps): object[]

Defined in: formatters/src/base-formatter.ts:867

Extract examples from a skill's nested examples property. Returns the same shape as extractExamples.

Parameters¶

skillProps¶

Record\<string, Value>

Returns¶

object[]

Inherited from¶

BaseFormatter.extractSkillExamples

extractSkills()¶

protected extractSkills(ast, options?): SkillFileConfig[]

Defined in: formatters/src/base-formatter.ts:1071

Extract skills from the

Parameters¶

ast¶

Program

options?¶

FormatOptions

Returns¶

SkillFileConfig[]

Skills¶

block, skipping unsafe names and skills excluded by the target's skill filter.

Inherited from¶

BaseFormatter.extractSkills

extractText()¶

protected extractText(content): string

Defined in: formatters/src/base-formatter.ts:88

Extract text from block content.

Parameters¶

content¶

BlockContent

Returns¶

string

Inherited from¶

BaseFormatter.extractText

findBlock()¶

protected findBlock(ast, name): Block | undefined

Defined in: formatters/src/base-formatter.ts:81

Find a block by name, ignoring internal blocks (starting with __).

Parameters¶

ast¶

Program

name¶

string

Returns¶

Block | undefined

Inherited from¶

BaseFormatter.findBlock

format()¶

format(ast, options?): FormatterOutput

Defined in: formatters/src/formatters/github.ts:244

Transform AST to target format

Parameters¶

ast¶

Program

options?¶

FormatOptions

Returns¶

FormatterOutput

Overrides¶

BaseFormatter.format

formatArray()¶

protected formatArray(arr): string

Defined in: formatters/src/base-formatter.ts:139

Format an array as comma-separated string.

Parameters¶

arr¶

unknown[]

Returns¶

string

Inherited from¶

BaseFormatter.formatArray

formatCanonical()¶

formatCanonical(ast, options?): FormatterOutput

Defined in: formatters/src/base-formatter.ts:40

Canonical entry point for legacy implementations.

Subclasses can override this method to consume ordered canonical entries directly. Until then, keep the compatibility projection isolated here.

Parameters¶

ast¶

CanonicalProgram

options?¶

FormatOptions

Returns¶

FormatterOutput

Inherited from¶

BaseFormatter.formatCanonical

formatStandardsList()¶

protected formatStandardsList(items): string[]

Defined in: formatters/src/base-formatter.ts:131

Format standards list from array of values (pass-through). Returns array of strings for rendering as bullet list.

Parameters¶

items¶

Value

Returns¶

string[]

Inherited from¶

BaseFormatter.formatStandardsList

generateSkillFile()¶

protected generateSkillFile(config, options?): FormatterOutput | null

Defined in: formatters/src/base-formatter.ts:1111

Render a skill file at the target's skill base path. Returns null when the target declares no skill support.

Parameters¶

config¶

SkillFileConfig

options?¶

FormatOptions

Returns¶

FormatterOutput | null

Inherited from¶

BaseFormatter.generateSkillFile

getArrayElements()¶

protected getArrayElements(content): Value[]

Defined in: formatters/src/base-formatter.ts:163

Extract array elements from block content.

Parameters¶

content¶

BlockContent

Returns¶

Value[]

Inherited from¶

BaseFormatter.getArrayElements

getBlockArrayElements()¶

protected getBlockArrayElements(block): Value[]

Defined in: formatters/src/base-formatter.ts:186

Parameters¶

block¶

Block

Returns¶

Value[]

Inherited from¶

BaseFormatter.getBlockArrayElements

getMetaField()¶

protected getMetaField(ast, key): string | undefined

Defined in: formatters/src/base-formatter.ts:153

Get meta field value as string.

Parameters¶

ast¶

Program

key¶

string

Returns¶

string | undefined

Inherited from¶

BaseFormatter.getMetaField

getNativeAgentName()¶

protected getNativeAgentName(ast, name): string

Defined in: formatters/src/base-formatter.ts:991

Return the deterministic native identifier for one agent.

Parameters¶

ast¶

Program

name¶

string

Returns¶

string

Inherited from¶

BaseFormatter.getNativeAgentName

getNativeAgentNameMap()¶

protected getNativeAgentNameMap(ast): ReadonlyMap\<string, string>

Defined in: formatters/src/base-formatter.ts:981

Map all agent names consistently for a target's native files.

Parameters¶

ast¶

Program

Returns¶

ReadonlyMap\<string, string>

Inherited from¶

BaseFormatter.getNativeAgentNameMap

getOutputPath()¶

protected getOutputPath(options?): string

Defined in: formatters/src/base-formatter.ts:74

Get the output path, respecting options override.

Parameters¶

options?¶

FormatOptions

Returns¶

string

Inherited from¶

BaseFormatter.getOutputPath

getPrettierOptions()¶

protected getPrettierOptions(options?): Required\<PrettierMarkdownOptions>

Defined in: formatters/src/base-formatter.ts:64

Get resolved Prettier options, merging provided options with defaults.

Parameters¶

options?¶

FormatOptions

Returns¶

Required\<PrettierMarkdownOptions>

Inherited from¶

BaseFormatter.getPrettierOptions

getProp()¶

protected getProp(content, key): Value | undefined

Defined in: formatters/src/base-formatter.ts:102

Get a specific property from block content.

Parameters¶

content¶

BlockContent

key¶

string

Returns¶

Value | undefined

Inherited from¶

BaseFormatter.getProp

getProps()¶

protected getProps(content): Record\<string, Value>

Defined in: formatters/src/base-formatter.ts:116

Get all properties from block content.

Parameters¶

content¶

BlockContent

Returns¶

Record\<string, Value>

Inherited from¶

BaseFormatter.getProps

getSkillBasePath()¶

getSkillBasePath(): string | null

Defined in: formatters/src/formatters/github.ts:232

Base path for skills, or null if formatter has no skill support.

Returns¶

string | null

Overrides¶

BaseFormatter.getSkillBasePath

getSkillFileName()¶

getSkillFileName(): string | null

Defined in: formatters/src/formatters/github.ts:236

Skill file name, or null if formatter has no skill support.

Returns¶

string | null

Overrides¶

BaseFormatter.getSkillFileName

humanizeLabel()¶

protected humanizeLabel(value): string

Defined in: formatters/src/base-formatter.ts:395

Convert a camelCase/kebab-case key into a human-readable label.

Parameters¶

value¶

string

Returns¶

string

Inherited from¶

BaseFormatter.humanizeLabel

isSafeAgentName()¶

protected isSafeAgentName(name): boolean

Defined in: formatters/src/base-formatter.ts:974

Check if an agent name is safe for use in file paths.

Parameters¶

name¶

string

Returns¶

boolean

Inherited from¶

BaseFormatter.isSafeAgentName

isSafeName()¶

protected isSafeName(name): boolean

Defined in: formatters/src/base-formatter.ts:954

Check if a name is safe for use in file paths. Rejects path traversal sequences and path separators.

Parameters¶

name¶

string

Returns¶

boolean

Inherited from¶

BaseFormatter.isSafeName

isSafeSkillName()¶

protected isSafeSkillName(name): boolean

Defined in: formatters/src/base-formatter.ts:967

Check if a skill name is safe for use in file paths.

Parameters¶

name¶

string

Returns¶

boolean

Inherited from¶

BaseFormatter.isSafeSkillName

mergeRequiredSkillFrontmatter()¶

protected mergeRequiredSkillFrontmatter(rawFrontmatter, name, description): string

Defined in: formatters/src/base-formatter.ts:1039

Preserve raw skill frontmatter while supplying mandatory skill fields.

Parameters¶

rawFrontmatter¶

string

name¶

string

description¶

string

Returns¶

string

Inherited from¶

BaseFormatter.mergeRequiredSkillFrontmatter

normalizeMarkdownForPrettier()¶

protected normalizeMarkdownForPrettier(content): string

Defined in: formatters/src/base-formatter.ts:437

Normalize markdown content to match Prettier formatting. - Strips common leading indentation from lines - Trims trailing whitespace from lines - Normalizes markdown table formatting - Adds blank lines before lists when preceded by text - Adds blank lines before code blocks when preceded by text - Escapes markdown special characters in paths

Parameters¶

content¶

string

Returns¶

string

Inherited from¶

BaseFormatter.normalizeMarkdownForPrettier

normalizeOutputDir()¶

protected normalizeOutputDir(dir): string

Defined in: formatters/src/base-formatter.ts:718

Normalize a user-provided output directory (from @use ... into "<path>" or skillTargets config) to a safe forward-slash relative path. Rejects .., . and leading slashes so the result can be appended to a target's dot-directory without escaping it.

Parameters¶

dir¶

string

Returns¶

string

Inherited from¶

BaseFormatter.normalizeOutputDir

normalizeResourcePath()¶

protected normalizeResourcePath(relativePath): string | null

Defined in: formatters/src/base-formatter.ts:781

Normalize a resource path to a safe, portable relative path.

Parameters¶

relativePath¶

string

Returns¶

string | null

Inherited from¶

BaseFormatter.normalizeResourcePath

referenceProvenance()¶

protected referenceProvenance(sourcePath): string

Defined in: formatters/src/base-formatter.ts:946

Generate a provenance comment for a reference file.

Parameters¶

sourcePath¶

string

Returns¶

string

Inherited from¶

BaseFormatter.referenceProvenance

referencesMode()¶

referencesMode(): "none" | "directory" | "inline"

Defined in: formatters/src/formatters/github.ts:240

How this formatter handles skill references. - 'directory': emit as separate files in references/ subdirectory - 'inline': append as sections in the main output file - 'none': references not supported

Returns¶

"none" | "directory" | "inline"

Overrides¶

BaseFormatter.referencesMode

renderCodeFence()¶

protected renderCodeFence(content, lang?): string

Defined in: formatters/src/base-formatter.ts:1183

Render content inside a code fence, using a longer fence if the content itself contains triple backticks (prevents code fence injection).

Parameters¶

content¶

string

lang?¶

string = ''

Returns¶

string

Inherited from¶

BaseFormatter.renderCodeFence

renderExamplesSection()¶

protected renderExamplesSection(ast, renderer, sectionName?): string | null

Defined in: formatters/src/base-formatter.ts:883

Render an examples section from the

Parameters¶

ast¶

Program

renderer¶

ConventionRenderer

sectionName?¶

string = 'Examples'

Custom section heading name (default: 'Examples')

Returns¶

string | null

Examples¶

block. Shared rendering logic used by Claude, GitHub, and MarkdownInstructionFormatter.

Inherited from¶

BaseFormatter.renderExamplesSection

resolveSkillDir()¶

protected resolveSkillDir(defaultSkillBasePath, skillName, outputDir?, options?): string

Defined in: formatters/src/base-formatter.ts:748

Resolve the directory for a generated skill, respecting per-target skill base overrides while preserving existing @use ... into behavior.

Parameters¶

defaultSkillBasePath¶

string

skillName¶

string

outputDir?¶

string

options?¶

FormatOptions

Returns¶

string

Inherited from¶

BaseFormatter.resolveSkillDir

sanitizeResourceFiles()¶

protected sanitizeResourceFiles(resources, targetDir): FormatterOutput[]

Defined in: formatters/src/base-formatter.ts:800

Filter resource files to only include safe canonical paths.

Parameters¶

resources¶

object[] | undefined

targetDir¶

string

Returns¶

FormatterOutput[]

Inherited from¶

BaseFormatter.sanitizeResourceFiles

shortcutSummary()¶

protected shortcutSummary(value, fallback?): string

Defined in: formatters/src/base-formatter.ts:233

Extract a stable one-line summary from any supported shortcut value.

Parameters¶

value¶

Value

fallback?¶

string = ''

Returns¶

string

Inherited from¶

BaseFormatter.shortcutSummary

shouldIncludeSkill()¶

protected shouldIncludeSkill(name, options?): boolean

Defined in: formatters/src/base-formatter.ts:737

Return true when the target configuration allows emitting the given skill.

Parameters¶

name¶

string

options?¶

FormatOptions

Returns¶

boolean

Inherited from¶

BaseFormatter.shouldIncludeSkill

stripAllIndent()¶

protected stripAllIndent(content): string

Defined in: formatters/src/base-formatter.ts:581

Strip all leading indentation from markdown content. Used for AGENTS.md where content from multiple sources has inconsistent indentation. Preserves indentation inside code blocks.

Parameters¶

content¶

string

Returns¶

string

Inherited from¶

BaseFormatter.stripAllIndent

transformInjectedSkillContent()¶

transformInjectedSkillContent(content): string

Defined in: formatters/src/base-formatter.ts:939

Default pass-through for injected skill content. Formatters whose target tools restrict skill frontmatter (e.g. Factory AI) override this hook to filter unsupported fields before the compiler writes the file.

Parameters¶

content¶

string

Returns¶

string

Inherited from¶

BaseFormatter.transformInjectedSkillContent

truncate()¶

protected truncate(str, max): string

Defined in: formatters/src/base-formatter.ts:146

Truncate string to max length with ellipsis.

Parameters¶

str¶

string

max¶

number

Returns¶

string

Inherited from¶

BaseFormatter.truncate

valueToString()¶

protected valueToString(value): string

Defined in: formatters/src/base-formatter.ts:213

Convert value to string representation.

Parameters¶

value¶

Value

Returns¶

string

Inherited from¶

BaseFormatter.valueToString

yamlQuoted()¶

protected yamlQuoted(value): string

Defined in: formatters/src/base-formatter.ts:267

Escape a value for use inside a double-quoted YAML scalar.

Parameters¶

value¶

string

Returns¶

string

Inherited from¶

BaseFormatter.yamlQuoted

yamlString()¶

protected yamlString(value): string

Defined in: formatters/src/base-formatter.ts:1010

Serialize a string as a YAML scalar, quoting only when required.

Parameters¶

value¶

string

Returns¶

string

Inherited from¶

BaseFormatter.yamlString

getSupportedVersions()¶

static getSupportedVersions(): object

Defined in: formatters/src/formatters/github.ts:228

Get supported versions for this formatter.

Returns¶

object

full¶

readonly full: object

full.description¶

readonly description: "Multifile + skills (.github/skills/) + agents (.github/agents/) + AGENTS.md" = 'Multifile + skills (.github/skills/) + agents (.github/agents/) + AGENTS.md'

full.name¶

readonly name: "full" = 'full'

full.outputPath¶

readonly outputPath: ".github/copilot-instructions.md" = '.github/copilot-instructions.md'

multifile¶

readonly multifile: object

multifile.description¶

readonly description: "Main + path-specific instructions (.github/instructions/) + prompts" = 'Main + path-specific instructions (.github/instructions/) + prompts'

multifile.name¶

readonly name: "multifile" = 'multifile'

multifile.outputPath¶

readonly outputPath: ".github/copilot-instructions.md" = '.github/copilot-instructions.md'

simple¶

readonly simple: object

simple.description¶

readonly description: "Single file output (.github/copilot-instructions.md)" = 'Single file output (.github/copilot-instructions.md)'

simple.name¶

readonly name: "simple" = 'simple'

simple.outputPath¶

readonly outputPath: ".github/copilot-instructions.md" = '.github/copilot-instructions.md'