How Improve-Claude-MD Handles the Commands Table in Markdown Files

Improve-claude-md detects, parses, and rewrites CLI commands tables by extracting pipe-delimited rows, prompting Claude to enhance only the description column, then replacing the original table with improved markdown.

The improve-claude-md skill in the humanlayer/skills repository is an Instagit plugin that automatically refines markdown documentation. When it encounters a commands table—a Markdown-formatted table listing CLI commands and their descriptions—the skill handles the table through a precise five-step pipeline that preserves command syntax while improving explanatory text.

---

How Improve-Claude-MD Detects the Commands Table

The skill locates commands tables using pattern-based detection rather than full markdown parsing.

In [agent-iteration.ts](https://github.com/humanlayer/skills/blob/main/plugins/improve-claude-md/skills/improve-claude-md/references/agent-iteration.ts), the implementation uses a regular expression matching ^\s*\|.*\|\s*$ to identify table boundaries. This regex finds lines starting and ending with pipe characters, which is the standard Markdown table syntax.

The skill specifically looks for tables containing a "Command" column in the header row. This targeted approach avoids false positives with other table types—such as configuration reference tables or comparison matrices—that might appear in the same document.

---

Parsing Pipe-Delimited Rows with Escape Handling

Once located, the skill extracts table data using a lightweight CSV-style parser adapted for Markdown's pipe delimiter.

The parsing logic:

• Splits each line on the | character
• Trims whitespace from each cell
• Handles escaped pipes (\|) to preserve command arguments that contain literal pipe characters

This deterministic parsing is critical for CLI documentation, where commands often include complex argument patterns like run --env <name> | jq '.status'. The escape handling ensures these constructs remain intact during extraction.

---

Building the LLM Prompt for Description Improvement

The skill constructs a targeted prompt that constrains Claude's output to prevent accidental command modification.

As documented in [SKILL.md](https://github.com/humanlayer/skills/blob/main/plugins/improve-claude-md/skills/improve-claude-md/SKILL.md), the prompt template follows this structure:

Improve the description column of the following commands table while keeping the command column unchanged.

```markdown
| Command | Description |
|---------|-------------|
| `run`   | Starts the service. |
| `stop`  | Halts the service. |

The table is wrapped in a fenced code block for clarity. The explicit instruction to preserve the command column acts as a guardrail, leveraging Claude's instruction-following capabilities to maintain semantic boundaries.

---

## Invoking Claude and Processing the Response

The skill sends the constructed prompt via `claudeClient.sendMessage` and expects a markdown table with identical column layout in return.

The response handling assumes:
- The output maintains the same header structure
- Only description cells contain modifications
- Rows remain in original order

If the response deviates—missing rows, reordered columns, or modified commands—the skill's replacement logic can detect mismatches and either reject the change or apply conservative merging.

---

## Replacing the Original Table in the Document

The final step swaps the original table block with the improved version while preserving all surrounding content.

The skill:
1. Identifies the exact line range of the original table
2. Splices in the new table at the same position
3. Writes the modified markdown back to the file system

This **surgical replacement** leaves code fences, headings, paragraphs, and other tables completely untouched. The idempotent design means running the skill repeatedly on an already-optimized file produces no further changes.

---

## Practical Example of improve-claude-md in Action

Input file [`docs/cli.md`](https://github.com/humanlayer/skills/blob/main/docs/cli.md):

```markdown

## Service Control

| Command | Description |
|---------|-------------|
| `run`   | Starts the service. |
| `stop`  | Halts the service. |

For more details, see the configuration guide.

Command execution:

instagit improve-claude-md docs/cli.md

Output file:

## Service Control

| Command | Description |
|---------|-------------|
| `run`   | Launches the service, initializing all required components and listening on the default port. |
| `stop`  | Gracefully shuts down the service, ensuring all pending operations are completed before termination. |

For more details, see the configuration guide.

The Command column remains identical; only descriptions are expanded with operational context.

---

Why the improve-claude-md Approach Works

Three architectural decisions make this commands table handling reliable:

• Regex-based detection avoids heavy dependencies while correctly identifying standard Markdown tables
• Column-constrained prompting prevents LLM hallucination from corrupting command syntax
• Surgical replacement preserves document integrity and enables safe automation

The skill's registration in [plugin.json](https://github.com/humanlayer/skills/blob/main/plugins/improve-claude-md/.claude-plugin/plugin.json) defines the permissions required for filesystem operations and LLM access, ensuring proper sandboxing within Instagit's plugin architecture.

---

Summary

• improve-claude-md targets commands tables by detecting pipe-delimited structures with "Command" headers
• Parsing handles escaped pipes to preserve complex CLI argument patterns during extraction
• Prompt engineering constrains Claude to rewrite only description columns, protecting command syntax
• Surgical replacement updates tables without affecting surrounding markdown content
• Idempotent operation prevents redundant processing of already-optimized documentation

---

Frequently Asked Questions

How does improve-claude-md distinguish commands tables from other markdown tables?

The skill uses a regular expression targeting lines bounded by pipe characters and specifically checks for a "Command" column in the header row. This filters out configuration tables, comparison matrices, and other tabular content that might appear in technical documentation.

What happens if a command contains a literal pipe character?

The parser respects escaped pipes (\|) during the splitting operation. This ensures commands with complex argument patterns—such as those using shell pipes—are correctly parsed as single cells rather than being split into separate columns.

Can improve-claude-md modify tables other than commands tables?

The current implementation focuses specifically on commands tables. For other table types—such as API parameter references or environment variable listings—the detection logic would need modification to recognize different header patterns and column structures.

Is the improve-claude-md skill safe to run in CI/CD pipelines?

Yes, the idempotent design makes it suitable for automation. Running the skill repeatedly produces no additional changes once descriptions are optimized. However, review the generated diffs before committing, as LLM output should always be validated for technical accuracy.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}