What happens to the original files?

The tool copies the Markdown files to the FTR docs folder and preserves the originals; imports are not destructive.

How is the date determined for generated frontmatter?

Date is derived from the file's modification time using the command shown in the steps (e.g., macOS: stat -f %Sm -t %Y-%m-%d ).

What if a file already has YAML frontmatter?

Existing frontmatter is preserved, and any missing required fields like date and tags are added automatically.

import-ftr

npx machina-cli add skill brennacodes/brenna-plugs/import --openclaw

Files (1)

SKILL.md

4.8 KB

<purpose> Import existing documentation files into `for-the-record/docs/`. The user specifies where to import from -- there is no default source directory. Generates proper frontmatter for each imported file. </purpose> <steps> <step id="load-config" number="1"> <description>Load Configuration</description>

<load-config>
  <action>Resolve the user's home directory.</action>
  <command language="bash" output="home" tool="Bash">echo $HOME</command>
  <constraint>Never pass `~` to the Read tool.</constraint>

  <read path="<home>/.things/config.json" output="config" />
  <if condition="config-missing">Tell the user: "Run `/things:setup-things` first." Then stop.<exit /></if>

  <read path="<home>/.things/for-the-record/preferences.json" output="preferences" />
  <if condition="preferences-missing">Tell the user: "Run `/setup-ftr` first." Then stop.<exit /></if>
</load-config>

</step> <step id="get-source" number="2"> <description>Get Source Directory</description>

<if condition="path-argument-provided">
  <action>Use the provided path as the source directory.</action>
</if>

<if condition="no-path-argument">
  <ask-user-question>
    <question>Where are the files you'd like to import?</question>
  </ask-user-question>
</if>

<action>Verify the path exists and is a directory.</action>
<if condition="path-not-found">Tell the user: "Directory not found: <path>." Then stop.<exit /></if>

</step> <step id="scan-source" number="3"> <description>Scan Source Directory</description>

<action>Scan the source directory for `.md` files. For each file, read the first ~10 lines to extract a brief description (first heading or first paragraph).</action>

<if condition="no-files-found">Tell the user: "No markdown files found in <path>." Then stop.<exit /></if>

<action>Show a numbered list:</action>
<output>
Files found in <source_dir>:
  1. filename.md -- "Brief description from content"
  2. another-file.md -- "Brief description"
  ...
</output>

<ask-user-question>
  <question>Which files would you like to import? Enter numbers (e.g., "1,3,5"), a range (e.g., "1-5"), or "all".</question>
</ask-user-question>

<if condition="--dry-run">
  <action>Show what WOULD happen for each selected file (generated filename, inferred tags, title) but don't write anything. Stop here.</action>
</if>

</step> <step id="import-files" number="4"> <description>Import Selected Files</description>

<action>For each selected file:</action>

1. Read the full content
2. Check if it already has YAML frontmatter
   - If yes: preserve existing frontmatter, add any missing required fields (`date`, `tags`)
   - If no: generate frontmatter:
     - `title`: from first `#` heading, or from filename (de-slugified)
     - `date`: from file modification time (`stat -f %Sm -t %Y-%m-%d <file>` on macOS)
     - `description`: first non-heading paragraph, truncated to 2 sentences
     - `detail_level`: `"detailed"` (imported files are typically full documents)
     - `source_type`: `"import"`
     - `tags`: auto-generated from content (technologies, keywords)
3. Generate filename: `<date>-<slugified-title>.md`
4. Write to `<home>/.things/for-the-record/docs/<filename>`

<constraint>Do not delete source files. Imports are copies.</constraint>

</step> <step id="git-workflow" number="5"> <description>Handle Git Workflow</description>

<git-workflow>
  <action>Read git workflow from `config.json` (`git.workflow`).</action>

  <if condition="workflow-auto">Automatically `git add`, `git commit -m "import: <N> documents into for-the-record"`, and `git push`.</if>
  <if condition="workflow-ask">
    <ask-user-question>
      <question>Commit and push the imported documents?</question>
      <option>Yes -- commit and push</option>
      <option>Commit only</option>
      <option>No -- I'll handle git myself</option>
    </ask-user-question>
  </if>
  <if condition="workflow-manual">Tell the user the files have been saved.</if>
</git-workflow>

</step> <step id="confirm" number="6"> <description>Confirm</description>

<completion-message>
Imported <N> documents into for-the-record:

<list of imported files with their generated titles and tags>

Find them: `/things:search-things --tag <tag>` or browse `~/.things/for-the-record/docs/`
</completion-message>

</step> </steps>

Source

git clone https://github.com/brennacodes/brenna-plugs/blob/main/plugins/for-the-record/skills/import/SKILL.mdView on GitHub

Overview

Imports existing Markdown docs from any directory into for-the-record/docs. It automatically generates frontmatter and tags for each file, ensuring consistent metadata. The user specifies the source directory and imports are copies, not deletions.

How This Skill Works

The skill accepts a source path, scans the directory for .md files, and reads each file. For each file, it checks for YAML frontmatter; if present, it preserves it and fills any missing fields like date and tags; if absent, it generates frontmatter using the first heading as the title (or filename if missing), the file’s modification time as date, a short description from the first non-heading paragraph, and auto-generated tags. It then writes a new Markdown file to ~/.things/for-the-record/docs/ with a date-prefixed slugified filename. Source files remain untouched; imports are copies.

When to Use It

You want to import a local repository of Markdown docs into for-the-record with consistent metadata.
You need to standardize frontmatter across a varied set of Markdown files before publishing.
You’re migrating documentation from a directory-by-directory structure into a centralized FTR docs folder.
You want automatic tag generation derived from content to improve searchability.
You must import from a specific source directory without a predefined default path.

Quick Start

Step 1: Provide the source path as an argument or trigger a prompt to specify the folder containing .md files.
Step 2: Review the listed Markdown candidates and select which files to import (or choose all).
Step 3: Run the import to write new files to ~/.things/for-the-record/docs/ with generated frontmatter.

Best Practices

Provide a clear, single source directory to avoid accidental imports from unintended locations.
Run a dry-run first to preview generated filenames, titles, and tags.
Check for existing frontmatter and ensure critical fields (date, tags) are present after import.
Verify the created filenames to ensure they reflect the content and date for easy sorting.
Keep the original source files intact; the tool creates copies in the FTR docs folder.

Example Use Cases

Migrate a project's internal Markdown docs from a local repo into for-the-record with consistent frontmatter.
Consolidate API reference Markdown files from multiple modules into a single FTR docs set.
Import team handbooks and knowledge base articles into FTR for centralized searchability.
Audit legacy documentation, enrich metadata, and import into for-the-record with generated tags.
Import multilingual docs by importing from language-specific folders and generating language-aware slugs.

Frequently Asked Questions

Add this skill to your agents