Dita Includes

List AsciiDoc Includes Skill

Recursively find all AsciiDoc files referenced via include:: directives in a document, traversing all child includes to build a complete dependency list.

Overview

This skill parses AsciiDoc files for include:: directives and follows them recursively to produce a complete, sorted, and deduplicated list of all referenced files. This is useful for:

• Understanding document structure before DITA conversion
• Identifying all files that compose an assembly
• Checking for missing or broken includes
• Preparing file lists for batch processing

What it does

Input: Assembly with nested includes

= Master Guide

include::_attributes/common.adoc[]

include::modules/con-intro.adoc[leveloffset=+1]

include::assemblies/getting-started.adoc[leveloffset=+1]

Where assemblies/getting-started.adoc contains:

= Getting Started

include::../modules/proc-install.adoc[leveloffset=+1]

include::../modules/proc-configure.adoc[leveloffset=+1]

Output: Complete file list (absolute paths)

/home/user/docs/_attributes/common.adoc
/home/user/docs/assemblies/getting-started.adoc
/home/user/docs/master.adoc
/home/user/docs/modules/con-intro.adoc
/home/user/docs/modules/proc-configure.adoc
/home/user/docs/modules/proc-install.adoc

Key features

• Recursive traversal: Follows includes in child files to any depth
• Cycle detection: Prevents infinite loops from circular includes
• Sorted output: Results are alphabetically sorted
• Deduplicated: Each file appears only once
• Absolute paths: Outputs absolute paths by default (works from any directory)
• Missing file handling: Reports files that don't exist (can be filtered)

Usage

bash ${CLAUDE_SKILL_DIR}/scripts/find_includes.sh  [options]

Options

| Option | Description | |--------|-------------| | -a, --absolute | Output absolute paths (default) | | -r, --relative | Output paths relative to input file directory | | -e, --existing | Only output files that exist | | -h, --help | Show help message |

Examples

# List all includes from an assembly (absolute paths by default)
bash ${CLAUDE_SKILL_DIR}/scripts/find_includes.sh master.adoc

# Get relative paths instead
bash ${CLAUDE_SKILL_DIR}/scripts/find_includes.sh docs/guide.adoc --relative

# Only list files that exist (skip broken includes)
bash ${CLAUDE_SKILL_DIR}/scripts/find_includes.sh master.adoc --existing

# Combine options
bash ${CLAUDE_SKILL_DIR}/scripts/find_includes.sh master.adoc -e

Limitations

• Attribute references: Paths containing {attribute} placeholders are skipped with a warning, as they cannot be resolved without knowing attribute values
• Conditional includes: The script does not evaluate ifdef/ifndef preprocessor directives; all includes are listed regardless of conditions

Example invocations

• "List all files included in master.adoc"
• "Find all includes in the assembly"
• "What files does this document depend on?"
• "Show me the include tree for the guide"
• "Check for missing includes"

Script location

scripts/
└── find_includes.sh      # Bash script for recursive include discovery

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: abhatt-rh
• Source: abhatt-rh/redhat-docs-agent-tools
• License: Apache-2.0
• Homepage: https://redhat-documentation.github.io/redhat-docs-agent-tools/

Install and usage instructions live in the source repository linked above.