BaseFormatter
Defined in: formatters/src/base-formatter.ts:28
Abstract base formatter with common helper methods. Extend this class to create new formatter implementations.
Extended by
MarkdownInstructionFormatterGitHubFormatterClaudeFormatterCursorFormatterAntigravityFormatterGrokFormatter
Implements
Constructors
Constructor
new BaseFormatter():
BaseFormatter
Returns
BaseFormatter
Properties
defaultConvention
abstractreadonlydefaultConvention:string
Defined in: formatters/src/base-formatter.ts:32
Default convention for this formatter
Implementation of
description
abstractreadonlydescription:string
Defined in: formatters/src/base-formatter.ts:31
Human-readable description
Implementation of
name
abstractreadonlyname:string
Defined in: formatters/src/base-formatter.ts:29
Unique formatter identifier
Implementation of
outputPath
abstractreadonlyoutputPath:string
Defined in: formatters/src/base-formatter.ts:30
Default output file path
Implementation of
standardsExtractor
protectedreadonlystandardsExtractor:StandardsExtractor
Defined in: formatters/src/base-formatter.ts:62
Shared standards extractor for consistent extraction across all formatters.
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.
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.
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
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[]
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
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
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
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
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[]
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.
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
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[]
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.
extractText()
protectedextractText(content):string
Defined in: formatters/src/base-formatter.ts:104
Extract text from block content.
Parameters
content
Returns
string
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
format()
abstractformat(ast,options?):FormatterOutput
Defined in: formatters/src/base-formatter.ts:33
Transform AST to target format
Parameters
ast
options?
Returns
Implementation of
formatArray()
protectedformatArray(arr):string
Defined in: formatters/src/base-formatter.ts:155
Format an array as comma-separated string.
Parameters
arr
unknown[]
Returns
string
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
Implementation of
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[]
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
getArrayElements()
protectedgetArrayElements(content):Value[]
Defined in: formatters/src/base-formatter.ts:179
Extract array elements from block content.
Parameters
content
Returns
Value[]
getBlockArrayElements()
protectedgetBlockArrayElements(block):Value[]
Defined in: formatters/src/base-formatter.ts:202
Parameters
block
Returns
Value[]
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
Implementation of
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
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
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>
getOutputPath()
protectedgetOutputPath(options?):string
Defined in: formatters/src/base-formatter.ts:90
Get the output path, respecting options override.
Parameters
options?
Returns
string
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>
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
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>
getSkillBasePath()
getSkillBasePath():
string|null
Defined in: formatters/src/base-formatter.ts:1097
Base path for skills, or null if formatter has no skill support.
Returns
string | null
Implementation of
getSkillFileName()
getSkillFileName():
string|null
Defined in: formatters/src/base-formatter.ts:1102
Skill file name, or null if formatter has no skill support.
Returns
string | null
Implementation of
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
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
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
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
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
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
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
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
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
referencesMode()
referencesMode():
"none"|"directory"|"inline"
Defined in: formatters/src/base-formatter.ts:1122
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"
Implementation of
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
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
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.
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
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
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.
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
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
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
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
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
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
Implementation of
Formatter.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
valueToString()
protectedvalueToString(value):string
Defined in: formatters/src/base-formatter.ts:229
Convert value to string representation.
Parameters
value
Returns
string
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
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