GitHubFormatter
Defined in: formatters/src/formatters/github.ts:192
Formatter for GitHub Copilot instructions.
Supports three versions:
- simple: Single
.github/copilot-instructions.mdfile - 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: fullSee
Extends
Constructors
Constructor
new GitHubFormatter():
GitHubFormatter
Returns
GitHubFormatter
Inherited from
Properties
defaultConvention
readonlydefaultConvention:"markdown"='markdown'
Defined in: formatters/src/formatters/github.ts:196
Default convention for this formatter
Overrides
BaseFormatter.defaultConvention
description
readonlydescription:"GitHub Copilot instructions (Markdown)"='GitHub Copilot instructions (Markdown)'
Defined in: formatters/src/formatters/github.ts:195
Human-readable description
Overrides
name
readonlyname:"github"='github'
Defined in: formatters/src/formatters/github.ts:193
Unique formatter identifier
Overrides
outputPath
readonlyoutputPath:".github/copilot-instructions.md"='.github/copilot-instructions.md'
Defined in: formatters/src/formatters/github.ts:194
Default output file path
Overrides
standardsExtractor
protectedreadonlystandardsExtractor:StandardsExtractor
Defined in: formatters/src/base-formatter.ts:62
Shared standards extractor for consistent extraction across all formatters.
Inherited from
BaseFormatter.standardsExtractor
CONTEXT_RENDERED_KEYS
protectedreadonlystaticCONTEXT_RENDERED_KEYS:ReadonlySet<string>
Defined in: formatters/src/base-formatter.ts:288
@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()
protectedappendGenericStandardItems(items,props,knownKeys):void
Defined in: formatters/src/base-formatter.ts:407
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()
protectedcontextArchitectureProperty(ast):string|null
Defined in: formatters/src/base-formatter.ts:308
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
Returns
string | null
Inherited from
BaseFormatter.contextArchitectureProperty
contextPropertyItems()
protectedcontextPropertyItems(ast,alsoRenderedKeys?):string[]
Defined in: formatters/src/base-formatter.ts:321
Render @context properties that no dedicated section consumes as
Label: value items, so structured context is never silently dropped.
Parameters
ast
alsoRenderedKeys?
readonly string[] = []
Returns
string[]
Inherited from
BaseFormatter.contextPropertyItems
contextTextConsumedByProject()
protectedcontextTextConsumedByProject(ast):boolean
Defined in: formatters/src/base-formatter.ts:274
Whether the @context block’s text is consumed by the project/intro
fallback. Must mirror the project() and intro() consumption conditions
exactly, otherwise the context section would either duplicate the text
(predicate too narrow) or drop it entirely (predicate too wide).
Parameters
ast
Returns
boolean
Inherited from
BaseFormatter.contextTextConsumedByProject
createRenderer()
protectedcreateRenderer(options?):ConventionRenderer
Defined in: formatters/src/base-formatter.ts:68
Create a convention renderer for this formatter. Uses the provided convention from options or falls back to the default.
Parameters
options?
Returns
Inherited from
dedent()
protecteddedent(text):string
Defined in: formatters/src/base-formatter.ts:863
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
documentationItem()
protecteddocumentationItem(value,defaultText):string|null
Defined in: formatters/src/base-formatter.ts:392
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()
protectedextractContextTechStackItems(props):string[]
Defined in: formatters/src/base-formatter.ts:354
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()
protectedextractExamples(ast):object[]
Defined in: formatters/src/base-formatter.ts:1036
Extract examples from the
Parameters
ast
Returns
object[]
Examples
block. Returns an array of example definitions with name, input, output, and optional description.
Inherited from
extractSectionWithCodeBlock()
protectedextractSectionWithCodeBlock(text,header):string|null
Defined in: formatters/src/base-formatter.ts:441
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()
protectedextractSkillExamples(skillProps):object[]
Defined in: formatters/src/base-formatter.ts:1049
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()
protectedextractSkills(ast,options?):SkillFileConfig[]
Defined in: formatters/src/base-formatter.ts:1297
Extract skills from the
Parameters
ast
options?
Returns
SkillFileConfig[]
Skills
block, skipping unsafe names and skills excluded by the target’s skill filter.
Inherited from
extractText()
protectedextractText(content):string
Defined in: formatters/src/base-formatter.ts:104
Extract text from block content.
Parameters
content
Returns
string
Inherited from
findBlock()
protectedfindBlock(ast,name):Block|undefined
Defined in: formatters/src/base-formatter.ts:97
Find a block by name, ignoring internal blocks (starting with __).
Parameters
ast
name
string
Returns
Block | undefined
Inherited from
format()
format(
input,options?):FormatterOutput
Defined in: formatters/src/formatters/github.ts:217
Transform AST to target format
Parameters
input
options?
Returns
Overrides
formatArray()
protectedformatArray(arr):string
Defined in: formatters/src/base-formatter.ts:155
Format an array as comma-separated string.
Parameters
arr
unknown[]
Returns
string
Inherited from
formatCanonical()
formatCanonical(
ast,options?):FormatterOutput
Defined in: formatters/src/base-formatter.ts:41
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
options?
Returns
Inherited from
formatStandardsList()
protectedformatStandardsList(items):string[]
Defined in: formatters/src/base-formatter.ts:147
Format standards list from array of values (pass-through). Returns array of strings for rendering as bullet list.
Parameters
items
Returns
string[]
Inherited from
BaseFormatter.formatStandardsList
generateSkillFile()
protectedgenerateSkillFile(config,options?):FormatterOutput|null
Defined in: formatters/src/base-formatter.ts:1337
Render a skill file at the target’s skill base path. Returns null when the target declares no skill support.
Parameters
config
SkillFileConfig
options?
Returns
FormatterOutput | null
Inherited from
BaseFormatter.generateSkillFile
getArrayElements()
protectedgetArrayElements(content):Value[]
Defined in: formatters/src/base-formatter.ts:179
Extract array elements from block content.
Parameters
content
Returns
Value[]
Inherited from
BaseFormatter.getArrayElements
getBlockArrayElements()
protectedgetBlockArrayElements(block):Value[]
Defined in: formatters/src/base-formatter.ts:202
Parameters
block
Returns
Value[]
Inherited from
BaseFormatter.getBlockArrayElements
getDotDir()
getDotDir():
string|null
Defined in: formatters/src/base-formatter.ts:1110
Dot directory of the target, by default the parent of a <dir>/skills
skill base path, or null when there is none.
Returns
string | null
Inherited from
getMetaField()
protectedgetMetaField(ast,key):string|undefined
Defined in: formatters/src/base-formatter.ts:169
Get meta field value as string.
Parameters
ast
key
string
Returns
string | undefined
Inherited from
getNativeAgentName()
protectedgetNativeAgentName(ast,name):string
Defined in: formatters/src/base-formatter.ts:1183
Return the deterministic native identifier for one agent.
Parameters
ast
name
string
Returns
string
Inherited from
BaseFormatter.getNativeAgentName
getNativeAgentNameMap()
protectedgetNativeAgentNameMap(ast):ReadonlyMap<string,string>
Defined in: formatters/src/base-formatter.ts:1173
Map all agent names consistently for a target’s native files.
Parameters
ast
Returns
ReadonlyMap<string, string>
Inherited from
BaseFormatter.getNativeAgentNameMap
getOutputPath()
protectedgetOutputPath(options?):string
Defined in: formatters/src/base-formatter.ts:90
Get the output path, respecting options override.
Parameters
options?
Returns
string
Inherited from
getPrettierOptions()
protectedgetPrettierOptions(options?):Required<PrettierMarkdownOptions>
Defined in: formatters/src/base-formatter.ts:80
Get resolved Prettier options, merging provided options with defaults.
Parameters
options?
Returns
Required<PrettierMarkdownOptions>
Inherited from
BaseFormatter.getPrettierOptions
getProp()
protectedgetProp(content,key):Value|undefined
Defined in: formatters/src/base-formatter.ts:118
Get a specific property from block content.
Parameters
content
key
string
Returns
Value | undefined
Inherited from
getProps()
protectedgetProps(content):Record<string,Value>
Defined in: formatters/src/base-formatter.ts:132
Get all properties from block content.
Parameters
content
Returns
Record<string, Value>
Inherited from
getSkillBasePath()
getSkillBasePath():
string|null
Defined in: formatters/src/formatters/github.ts:205
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:209
Skill file name, or null if formatter has no skill support.
Returns
string | null
Overrides
BaseFormatter.getSkillFileName
humanizeLabel()
protectedhumanizeLabel(value):string
Defined in: formatters/src/base-formatter.ts:427
Convert a camelCase/kebab-case key into a human-readable label.
Parameters
value
string
Returns
string
Inherited from
isSafeAgentName()
protectedisSafeAgentName(name):boolean
Defined in: formatters/src/base-formatter.ts:1166
Check if an agent name is safe for use in file paths.
Parameters
name
string
Returns
boolean
Inherited from
isSafeName()
protectedisSafeName(name):boolean
Defined in: formatters/src/base-formatter.ts:1146
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
isSafeSkillName()
protectedisSafeSkillName(name):boolean
Defined in: formatters/src/base-formatter.ts:1159
Check if a skill name is safe for use in file paths.
Parameters
name
string
Returns
boolean
Inherited from
mergeRequiredSkillFrontmatter()
protectedmergeRequiredSkillFrontmatter(rawFrontmatter,name,description):string
Defined in: formatters/src/base-formatter.ts:1265
Preserve raw skill frontmatter while supplying mandatory skill fields.
Parameters
rawFrontmatter
string
name
string
description
string
Returns
string
Inherited from
BaseFormatter.mergeRequiredSkillFrontmatter
normalizeMarkdownForPrettier()
protectednormalizeMarkdownForPrettier(content):string
Defined in: formatters/src/base-formatter.ts:501
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
The result must keep the meaning of the input: table cells, code spans and list nesting (including tight lists) are never changed.
With verbatimMarkdown (formatting.postFormat: false) only the common
indentation is removed and the text stays as written.
Parameters
content
string
Returns
string
Inherited from
BaseFormatter.normalizeMarkdownForPrettier
normalizeOutputDir()
protectednormalizeOutputDir(dir):string
Defined in: formatters/src/base-formatter.ts:896
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()
protectednormalizeResourcePath(relativePath):string|null
Defined in: formatters/src/base-formatter.ts:963
Normalize a resource path to a safe, portable relative path.
Parameters
relativePath
string
Returns
string | null
Inherited from
BaseFormatter.normalizeResourcePath
referenceProvenance()
protectedreferenceProvenance(sourcePath):string
Defined in: formatters/src/base-formatter.ts:1138
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:213
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
removeRawFrontmatterKeys()
protectedremoveRawFrontmatterKeys(rawFrontmatter,keys):string
Defined in: formatters/src/base-formatter.ts:1233
Remove top-level keys (with their nested lines) from raw SKILL.md
frontmatter. Used for PromptScript-only keys such as params, which are
resolved at compile time and mean nothing to the target tool.
Parameters
rawFrontmatter
string
keys
ReadonlySet<string>
Returns
string
Inherited from
BaseFormatter.removeRawFrontmatterKeys
renderCodeFence()
protectedrenderCodeFence(content,lang?):string
Defined in: formatters/src/base-formatter.ts:1409
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
renderExamplesSection()
protectedrenderExamplesSection(ast,renderer,sectionName?):string|null
Defined in: formatters/src/base-formatter.ts:1065
Render an examples section from the
Parameters
ast
renderer
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()
protectedresolveSkillDir(defaultSkillBasePath,skillName,outputDir?,options?):string
Defined in: formatters/src/base-formatter.ts:926
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?
Returns
string
Inherited from
sanitizeResourceFiles()
protectedsanitizeResourceFiles(resources,targetDir):FormatterOutput[]
Defined in: formatters/src/base-formatter.ts:982
Filter resource files to only include safe canonical paths.
Parameters
resources
object[] | undefined
targetDir
string
Returns
Inherited from
BaseFormatter.sanitizeResourceFiles
shiftContextHeadings()
protectedshiftContextHeadings(text):string
Defined in: formatters/src/base-formatter.ts:846
Shift
Parameters
text
string
Returns
string
Context
headings so none of them reaches the formatter’s own h1 and h2 levels. All headings move by the same amount, so their relative levels stay as written. Text that already starts at h3 or deeper is kept as is.
Inherited from
BaseFormatter.shiftContextHeadings
shiftHeadingsToMinLevel()
protectedshiftHeadingsToMinLevel(text,targetLevel):string
Defined in: formatters/src/base-formatter.ts:807
Shift all ATX headings by the same amount so the shallowest heading lands at targetLevel. Levels clamp to h1-h6 and fenced code blocks are ignored.
Parameters
text
string
targetLevel
number
Returns
string
Inherited from
BaseFormatter.shiftHeadingsToMinLevel
shortcutSummary()
protectedshortcutSummary(value,fallback?):string
Defined in: formatters/src/base-formatter.ts:249
Extract a stable one-line summary from any supported shortcut value.
Parameters
value
fallback?
string = ''
Returns
string
Inherited from
shouldIncludeSkill()
protectedshouldIncludeSkill(name,options?):boolean
Defined in: formatters/src/base-formatter.ts:915
Return true when the target configuration allows emitting the given skill.
Parameters
name
string
options?
Returns
boolean
Inherited from
BaseFormatter.shouldIncludeSkill
startFormat()
protectedstartFormat(options?):void
Defined in: formatters/src/base-formatter.ts:55
Call first in format, so markdown helpers know whether to keep the text
as written. The state is reset on every call.
Parameters
options?
Returns
void
Inherited from
stripAllIndent()
protectedstripAllIndent(content):string
Defined in: formatters/src/base-formatter.ts:673
Strip all leading indentation from markdown content. Used for AGENTS.md where content from multiple sources has inconsistent indentation. Preserves indentation inside code blocks.
With verbatimMarkdown only the common indentation is removed.
Parameters
content
string
Returns
string
Inherited from
transformInjectedSkillContent()
transformInjectedSkillContent(
content):string
Defined in: formatters/src/base-formatter.ts:1131
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()
protectedtruncate(str,max):string
Defined in: formatters/src/base-formatter.ts:162
Truncate string to max length with ellipsis.
Parameters
str
string
max
number
Returns
string
Inherited from
valueToString()
protectedvalueToString(value):string
Defined in: formatters/src/base-formatter.ts:229
Convert value to string representation.
Parameters
value
Returns
string
Inherited from
yamlQuoted()
protectedyamlQuoted(value):string
Defined in: formatters/src/base-formatter.ts:299
Escape a value for use inside a double-quoted YAML scalar.
Parameters
value
string
Returns
string
Inherited from
yamlString()
protectedyamlString(value):string
Defined in: formatters/src/base-formatter.ts:1202
Serialize a string as a YAML scalar, quoting only when required.
Parameters
value
string
Returns
string
Inherited from
getSupportedVersions()
staticgetSupportedVersions():object
Defined in: formatters/src/formatters/github.ts:201
Get supported versions for this formatter.
Returns
object
full
readonlyfull:object
full.description
readonlydescription:"Multifile + skills (.github/skills/) + agents (.github/agents/) + AGENTS.md"='Multifile + skills (.github/skills/) + agents (.github/agents/) + AGENTS.md'
full.name
readonlyname:"full"='full'
full.outputPath
readonlyoutputPath:".github/copilot-instructions.md"='.github/copilot-instructions.md'
multifile
readonlymultifile:object
multifile.description
readonlydescription:"Main + path-specific instructions (.github/instructions/) + prompts"='Main + path-specific instructions (.github/instructions/) + prompts'
multifile.name
readonlyname:"multifile"='multifile'
multifile.outputPath
readonlyoutputPath:".github/copilot-instructions.md"='.github/copilot-instructions.md'
simple
readonlysimple:object
simple.description
readonlydescription:"Single file output (.github/copilot-instructions.md)"='Single file output (.github/copilot-instructions.md)'
simple.name
readonlyname:"simple"='simple'
simple.outputPath
readonlyoutputPath:".github/copilot-instructions.md"='.github/copilot-instructions.md'