CodexFormatter
Defined in: formatters/src/formatters/codex.ts:285
Native Codex formatter.
Generates:
- Root
AGENTS.mdthrough MarkdownInstructionFormatter .codex/agents/<name>.tomlfor each agent in
Agents
.agents/skills/<name>/SKILL.mdfor skills (fixture-confirmed path)
Agent field mapping:
content->developer_instructionsreasoningEffort->model_reasoning_effortsandboxMode->sandbox_modenicknameCandidates->nickname_candidatesmcpServers->mcp_serversskills->skills.config
Extends
Constructors
Constructor
new CodexFormatter():
CodexFormatter
Defined in: formatters/src/formatters/codex.ts:286
Returns
CodexFormatter
Overrides
MarkdownInstructionFormatter.constructor
Properties
config
protectedreadonlyconfig:MarkdownFormatterConfig
Defined in: formatters/src/markdown-instruction-formatter.ts:163
Inherited from
MarkdownInstructionFormatter.config
defaultConvention
readonlydefaultConvention:string
Defined in: formatters/src/markdown-instruction-formatter.ts:161
Default convention for this formatter
Inherited from
MarkdownInstructionFormatter.defaultConvention
description
readonlydescription:string
Defined in: formatters/src/markdown-instruction-formatter.ts:160
Human-readable description
Inherited from
MarkdownInstructionFormatter.description
name
readonlyname:string
Defined in: formatters/src/markdown-instruction-formatter.ts:158
Unique formatter identifier
Inherited from
MarkdownInstructionFormatter.name
outputPath
readonlyoutputPath:string
Defined in: formatters/src/markdown-instruction-formatter.ts:159
Default output file path
Inherited from
MarkdownInstructionFormatter.outputPath
standardsExtractor
protectedreadonlystandardsExtractor:StandardsExtractor
Defined in: formatters/src/base-formatter.ts:62
Shared standards extractor for consistent extraction across all formatters.
Inherited from
MarkdownInstructionFormatter.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
MarkdownInstructionFormatter.CONTEXT_RENDERED_KEYS
Methods
addCommonSections()
protectedaddCommonSections(ast,renderer,sections):void
Defined in: formatters/src/markdown-instruction-formatter.ts:645
Parameters
ast
renderer
sections
string[]
Returns
void
Inherited from
MarkdownInstructionFormatter.addCommonSections
addSection()
protectedaddSection(sections,content):void
Defined in: formatters/src/markdown-instruction-formatter.ts:666
Parameters
sections
string[]
content
string | null
Returns
void
Inherited from
MarkdownInstructionFormatter.addSection
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
MarkdownInstructionFormatter.appendGenericStandardItems
architecture()
protectedarchitecture(ast,renderer):string|null
Defined in: formatters/src/markdown-instruction-formatter.ts:761
Parameters
ast
renderer
Returns
string | null
Inherited from
MarkdownInstructionFormatter.architecture
codeStandards()
protectedcodeStandards(ast,renderer):string|null
Defined in: formatters/src/markdown-instruction-formatter.ts:831
Parameters
ast
renderer
Returns
string | null
Inherited from
MarkdownInstructionFormatter.codeStandards
commands()
protectedcommands(ast,renderer):string|null
Defined in: formatters/src/markdown-instruction-formatter.ts:900
Parameters
ast
renderer
Returns
string | null
Inherited from
MarkdownInstructionFormatter.commands
configFiles()
protectedconfigFiles(ast,renderer):string|null
Defined in: formatters/src/markdown-instruction-formatter.ts:877
Parameters
ast
renderer
Returns
string | null
Inherited from
MarkdownInstructionFormatter.configFiles
context()
protectedcontext(ast,renderer):string|null
Defined in: formatters/src/markdown-instruction-formatter.ts:798
Render
Parameters
ast
renderer
Returns
string | null
Context
block text content as a ”## Context” section.
The ”## Architecture” subsection (with code block) is stripped because it is already rendered separately by architecture. Remaining headings are shifted below h2, keeping their relative levels, to avoid clashing with the formatter’s own h2 section headings. When no
Identity
block exists, the project() fallback already consumes the full
Context
text, so only the generic properties are rendered to avoid duplication.
Inherited from
MarkdownInstructionFormatter.context
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
MarkdownInstructionFormatter.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
MarkdownInstructionFormatter.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
MarkdownInstructionFormatter.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
MarkdownInstructionFormatter.createRenderer
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
MarkdownInstructionFormatter.dedent
diagrams()
protecteddiagrams(ast,renderer):string|null
Defined in: formatters/src/markdown-instruction-formatter.ts:994
Parameters
ast
renderer
Returns
string | null
Inherited from
MarkdownInstructionFormatter.diagrams
documentation()
protecteddocumentation(ast,renderer):string|null
Defined in: formatters/src/markdown-instruction-formatter.ts:963
Parameters
ast
renderer
Returns
string | null
Inherited from
MarkdownInstructionFormatter.documentation
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
MarkdownInstructionFormatter.documentationItem
examples()
protectedexamples(ast,renderer):string|null
Defined in: formatters/src/markdown-instruction-formatter.ts:1083
Parameters
ast
renderer
Returns
string | null
Inherited from
MarkdownInstructionFormatter.examples
extractAgents()
protectedextractAgents(ast,_options?):MarkdownAgentConfig[]
Defined in: formatters/src/markdown-instruction-formatter.ts:584
Parameters
ast
_options?
Returns
Inherited from
MarkdownInstructionFormatter.extractAgents
extractCommands()
protectedextractCommands(ast):MarkdownCommandConfig[]
Defined in: formatters/src/markdown-instruction-formatter.ts:510
Parameters
ast
Returns
Inherited from
MarkdownInstructionFormatter.extractCommands
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
MarkdownInstructionFormatter.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
MarkdownInstructionFormatter.extractExamples
extractRestrictionsItems()
protectedextractRestrictionsItems(block):string[]
Defined in: formatters/src/markdown-instruction-formatter.ts:1091
Parameters
block
Returns
string[]
Inherited from
MarkdownInstructionFormatter.extractRestrictionsItems
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
MarkdownInstructionFormatter.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
MarkdownInstructionFormatter.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
MarkdownInstructionFormatter.extractSkills
extractTechStackFromContext()
protectedextractTechStackFromContext(context):string[]
Defined in: formatters/src/markdown-instruction-formatter.ts:740
Parameters
context
Block | undefined
Returns
string[]
Inherited from
MarkdownInstructionFormatter.extractTechStackFromContext
extractTechStackFromStandards()
protectedextractTechStackFromStandards(standards):string[]
Defined in: formatters/src/markdown-instruction-formatter.ts:745
Parameters
standards
Block | undefined
Returns
string[]
Inherited from
MarkdownInstructionFormatter.extractTechStackFromStandards
extractText()
protectedextractText(content):string
Defined in: formatters/src/base-formatter.ts:104
Extract text from block content.
Parameters
content
Returns
string
Inherited from
MarkdownInstructionFormatter.extractText
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
MarkdownInstructionFormatter.findBlock
format()
format(
ast,options?):FormatterOutput
Defined in: formatters/src/formatters/codex.ts:386
Override format to inject additional agent fields from the AST.
Parameters
ast
options?
Returns
Overrides
MarkdownInstructionFormatter.format
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
MarkdownInstructionFormatter.formatArray
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
MarkdownInstructionFormatter.formatCanonical
formatFull()
protectedformatFull(ast,options?):FormatterOutput
Defined in: formatters/src/markdown-instruction-formatter.ts:384
Parameters
ast
options?
Returns
Inherited from
MarkdownInstructionFormatter.formatFull
formatMultifile()
protectedformatMultifile(ast,options?):FormatterOutput
Defined in: formatters/src/markdown-instruction-formatter.ts:337
Parameters
ast
options?
Returns
Inherited from
MarkdownInstructionFormatter.formatMultifile
formatSimple()
protectedformatSimple(ast,options?):FormatterOutput
Defined in: formatters/src/markdown-instruction-formatter.ts:312
Parameters
ast
options?
Returns
Inherited from
MarkdownInstructionFormatter.formatSimple
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
MarkdownInstructionFormatter.formatStandardsList
generateAgentFile()
protectedgenerateAgentFile(config):FormatterOutput
Defined in: formatters/src/formatters/codex.ts:360
Generate agent TOML files for Codex. Overrides the base agent file generation to emit TOML instead of Markdown. This is a fallback for when the full AST data is not available; the format() override handles the complete field mapping.
Parameters
config
Returns
Overrides
MarkdownInstructionFormatter.generateAgentFile
generateCommandFile()
protectedgenerateCommandFile(config):FormatterOutput
Defined in: formatters/src/markdown-instruction-formatter.ts:553
Parameters
config
Returns
Inherited from
MarkdownInstructionFormatter.generateCommandFile
generateFrontmatter()
protectedgenerateFrontmatter(ast,options?):string|undefined
Defined in: formatters/src/formatters/codex.ts:309
Generate optional AGENTS.md v1.1 frontmatter when agentsFrontmatter is ‘experimental’. Reads description and tags from the
Parameters
ast
options?
Returns
string | undefined
Meta
block.
Overrides
MarkdownInstructionFormatter.generateFrontmatter
generateMcpConfig()
protectedgenerateMcpConfig(ast):FormatterOutput|undefined
Defined in: formatters/src/markdown-instruction-formatter.ts:447
Generate MCP config file from
Parameters
ast
Returns
FormatterOutput | undefined
Mcp Servers
block if configured. Returns FormatterOutput or undefined if no MCP block or no config path.
Inherited from
MarkdownInstructionFormatter.generateMcpConfig
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
MarkdownInstructionFormatter.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
MarkdownInstructionFormatter.getArrayElements
getBlockArrayElements()
protectedgetBlockArrayElements(block):Value[]
Defined in: formatters/src/base-formatter.ts:202
Parameters
block
Returns
Value[]
Inherited from
MarkdownInstructionFormatter.getBlockArrayElements
getDotDir()
getDotDir():
string|null
Defined in: formatters/src/formatters/codex.ts:379
Codex keeps its own files in .codex; skills live in .agents/skills.
Returns
string | null
Overrides
MarkdownInstructionFormatter.getDotDir
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
MarkdownInstructionFormatter.getMetaField
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
MarkdownInstructionFormatter.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
MarkdownInstructionFormatter.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
MarkdownInstructionFormatter.getOutputPath
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
MarkdownInstructionFormatter.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
MarkdownInstructionFormatter.getProp
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
MarkdownInstructionFormatter.getProps
getRenderedSectionName()
protectedgetRenderedSectionName(ast,key,renderer,defaultTitle?):string
Defined in: formatters/src/markdown-instruction-formatter.ts:485
Parameters
ast
key
renderer
defaultTitle?
string
Returns
string
Inherited from
MarkdownInstructionFormatter.getRenderedSectionName
getSectionName()
protectedgetSectionName(ast,key,defaultTitle?):string
Defined in: formatters/src/markdown-instruction-formatter.ts:478
Parameters
ast
key
defaultTitle?
string
Returns
string
Inherited from
MarkdownInstructionFormatter.getSectionName
getSkillBasePath()
getSkillBasePath():
string|null
Defined in: formatters/src/markdown-instruction-formatter.ts:174
Base path for skills, or null if formatter has no skill support.
Returns
string | null
Inherited from
MarkdownInstructionFormatter.getSkillBasePath
getSkillFileName()
getSkillFileName():
string|null
Defined in: formatters/src/markdown-instruction-formatter.ts:179
Skill file name, or null if formatter has no skill support.
Returns
string | null
Inherited from
MarkdownInstructionFormatter.getSkillFileName
getUnsupportedBlockSuggestion()
protectedgetUnsupportedBlockSuggestion(blockName):string
Defined in: formatters/src/markdown-instruction-formatter.ts:278
Provide a safe migration path for an omitted block.
Parameters
blockName
string
Returns
string
Inherited from
MarkdownInstructionFormatter.getUnsupportedBlockSuggestion
getUnsupportedBlockWarnings()
protectedgetUnsupportedBlockWarnings(ast,skippedBlocks?):FormatterWarning[]
Defined in: formatters/src/markdown-instruction-formatter.ts:249
Report blocks that have no verified project-local output contract. Native target files are never invented for these blocks.
Parameters
ast
skippedBlocks?
ReadonlySet<string> = ...
Returns
Inherited from
MarkdownInstructionFormatter.getUnsupportedBlockWarnings
gitCommits()
protectedgitCommits(ast,renderer):string|null
Defined in: formatters/src/markdown-instruction-formatter.ts:850
Parameters
ast
renderer
Returns
string | null
Inherited from
MarkdownInstructionFormatter.gitCommits
hasEnabledHooks()
protectedhasEnabledHooks(ast):boolean
Defined in: formatters/src/markdown-instruction-formatter.ts:233
Parameters
ast
Returns
boolean
Inherited from
MarkdownInstructionFormatter.hasEnabledHooks
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
MarkdownInstructionFormatter.humanizeLabel
isBlockUnsupported()
protectedisBlockUnsupported(blockName):boolean
Defined in: formatters/src/markdown-instruction-formatter.ts:941
Parameters
blockName
string
Returns
boolean
Inherited from
MarkdownInstructionFormatter.isBlockUnsupported
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
MarkdownInstructionFormatter.isSafeAgentName
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
MarkdownInstructionFormatter.isSafeName
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
MarkdownInstructionFormatter.isSafeSkillName
knowledgeContent()
protectedknowledgeContent(ast,renderer,includeResolvedTitle?):string|null
Defined in: formatters/src/markdown-instruction-formatter.ts:1023
Render remaining
Parameters
ast
renderer
includeResolvedTitle?
boolean = true
Returns
string | null
Knowledge
text content that isn’t consumed by other sections. Strips ”## Development Commands” and ”## Post-Work Verification” sub-sections since those are already rendered by commands() and postWork().
Inherited from
MarkdownInstructionFormatter.knowledgeContent
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
MarkdownInstructionFormatter.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
MarkdownInstructionFormatter.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
MarkdownInstructionFormatter.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
MarkdownInstructionFormatter.normalizeResourcePath
postWork()
protectedpostWork(ast,renderer):string|null
Defined in: formatters/src/markdown-instruction-formatter.ts:945
Parameters
ast
renderer
Returns
string | null
Inherited from
MarkdownInstructionFormatter.postWork
project()
protectedproject(ast,renderer):string|null
Defined in: formatters/src/markdown-instruction-formatter.ts:670
Parameters
ast
renderer
Returns
string | null
Inherited from
MarkdownInstructionFormatter.project
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
MarkdownInstructionFormatter.referenceProvenance
referencesMode()
referencesMode():
"none"|"directory"|"inline"
Defined in: formatters/src/markdown-instruction-formatter.ts:188
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"
Inherited from
MarkdownInstructionFormatter.referencesMode
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
MarkdownInstructionFormatter.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
MarkdownInstructionFormatter.renderCodeFence
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
MarkdownInstructionFormatter.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
MarkdownInstructionFormatter.resolveSkillDir
resolveVersion()
protectedresolveVersion(version?):MarkdownVersion
Defined in: formatters/src/markdown-instruction-formatter.ts:302
Parameters
version?
string
Returns
Inherited from
MarkdownInstructionFormatter.resolveVersion
restrictions()
protectedrestrictions(ast,renderer):string|null
Defined in: formatters/src/markdown-instruction-formatter.ts:1070
Parameters
ast
renderer
Returns
string | null
Inherited from
MarkdownInstructionFormatter.restrictions
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
MarkdownInstructionFormatter.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
MarkdownInstructionFormatter.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
MarkdownInstructionFormatter.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
MarkdownInstructionFormatter.shortcutSummary
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
MarkdownInstructionFormatter.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
MarkdownInstructionFormatter.startFormat
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
MarkdownInstructionFormatter.stripAllIndent
techStack()
protectedtechStack(ast,renderer):string|null
Defined in: formatters/src/markdown-instruction-formatter.ts:710
Parameters
ast
renderer
Returns
string | null
Inherited from
MarkdownInstructionFormatter.techStack
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
MarkdownInstructionFormatter.transformInjectedSkillContent
transformRestrictionItem()
protectedtransformRestrictionItem(s):string
Defined in: formatters/src/markdown-instruction-formatter.ts:502
Parameters
s
string
Returns
string
Inherited from
MarkdownInstructionFormatter.transformRestrictionItem
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
MarkdownInstructionFormatter.truncate
valueToString()
protectedvalueToString(value):string
Defined in: formatters/src/base-formatter.ts:229
Convert value to string representation.
Parameters
value
Returns
string
Inherited from
MarkdownInstructionFormatter.valueToString
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
MarkdownInstructionFormatter.yamlQuoted
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
MarkdownInstructionFormatter.yamlString
getSupportedVersions()
staticgetSupportedVersions():FormatterVersionMap
Defined in: formatters/src/formatters/codex.ts:301