enhance-cross-file
Analyze cross-file semantic consistency across agents, skills, and workflows.
Parse Arguments
const args = '$ARGUMENTS'.split(' ').filter(Boolean); const targetPath = args.find(a => !a.startsWith('--')) || '.';
Purpose
Detects issues that span multiple files - things single-file analysis misses:
-
Tools used in prompt body but not declared in frontmatter
-
Agent references that don't exist
-
Duplicate instructions across files (maintenance burden)
-
Contradictory rules (ALWAYS vs NEVER conflicts)
-
Orphaned agents not referenced by any workflow
-
Skill tool mismatches (allowed-tools vs actual usage)
Workflow
Run Analyzer - Execute the JavaScript analyzer to get findings:
node -e "const a = require('./lib/enhance/cross-file-analyzer.js'); console.log(JSON.stringify(a.analyze('.'), null, 2));"
For a specific path: a.analyze('./plugins/enhance')
Parse Results - The analyzer returns JSON with summary and findings
Report - Return findings grouped by category
The JavaScript analyzer (lib/enhance/cross-file-analyzer.js ) implements all cross-file detection. The patterns below are reference documentation.
Detection Patterns
- Tool Consistency (MEDIUM Certainty)
tool_not_in_allowed_list: Tool used in prompt body but not in frontmatter tools: list
Frontmatter declares:
tools: Read, Grep
But body uses:
Use Write({ file_path: "/out" }) # <- Not declared!
skill_tool_mismatch: Skill's allowed-tools doesn't match actual tool usage in skill body
- Workflow Consistency (MEDIUM Certainty)
missing_workflow_agent: subagent_type: "plugin:agent-name" references non-existent agent
orphaned_prompt: Agent file exists but no workflow references it (may be entry point - check manually)
incomplete_phase_transition: Workflow phase mentions "Phase N" but no corresponding section
- Instruction Consistency (MEDIUM Certainty)
duplicate_instructions: Same MUST/NEVER instruction in 3+ files (extract to shared location)
contradictory_rules: One file says "ALWAYS X" while another says "NEVER X"
Output Format
Cross-File Analysis
Files Analyzed: {agents} agents, {skills} skills, {commands} commands
Tool Consistency ({n})
| Agent | Issue | Fix |
|---|---|---|
| exploration-agent | Uses Write but not in tools list | Add Write to frontmatter |
Workflow Issues ({n})
| Source | Issue | Fix |
|---|---|---|
| workflow.md | References nonexistent agent | Check spelling or create agent |
Instruction Consistency ({n})
| Instruction | Files | Fix |
|---|---|---|
| "NEVER push --force" | 4 files | Extract to CLAUDE.md |
Constraints
-
All patterns are MEDIUM certainty (require context)
-
No auto-fix (cross-file changes need human review)
-
Skip content inside <bad-example> , <bad_example> , <badexample> tags
-
Skip content inside code blocks with "bad" in info string
-
Entry point agents (orchestrator, validator, discoverer) are not orphaned
Pattern Statistics
Category Patterns Auto-Fixable
Tool Consistency 2 0
Workflow 3 0
Consistency 3 0
Total 8 0