Skip to main content

File Structure Analysis Skill

Overview​

Skill for analyzing project file and directory structure against CODITECT standards. Identifies organizational issues, naming violations, and produces actionable reports.

When to Use​

Use this skill when:

  • Assessing a project's current organizational state
  • Identifying what needs to be fixed before production
  • Generating metrics on project quality
  • Creating baseline for improvement tracking
  • Auditing projects for compliance

Capabilities​

Level 1: Quick Scan​

  • Check root-level structure
  • Identify obvious issues
  • Basic compliance score

Level 2: Full Analysis​

  • Complete directory traversal
  • Naming convention validation
  • README coverage calculation
  • Detailed issue categorization

Level 3: Deep Audit​

  • All Level 2 capabilities
  • Cross-reference validation
  • Frontmatter compliance
  • Git history analysis
  • Security scan

Analysis Categories​

CategoryWeightWhat's Checked
Structure25%Directory hierarchy
Naming20%File/dir naming
Documentation20%README coverage
Organization15%Files in right places
Frontmatter10%Metadata compliance
Other10%Various checks

Usage​

Quick Scan​

/agent project-structure-analyzer "Quick scan of root directory"

Full Analysis​

/agent project-structure-analyzer "Complete structure analysis"

Specific Directory​

/agent project-structure-analyzer "Analyze docs/ directory"

Output​

Analysis Report​

# Structure Analysis Report

## Score: XX/100 (Grade X)

## Issues by Severity
- Critical: X
- High: X
- Medium: X
- Low: X

## Directory Structure
[Current tree structure]

## Issues Found
[Categorized issue list]

## Recommendations
[Prioritized fix list]

Standards Reference​

  • DIRECTORY-STRUCTURE-STANDARD.md
  • FILE-NAMING-CONVENTIONS.md
  • README-STANDARD.md
  • FRONTMATTER-STANDARD.md
  • project-organization - Fix issues found
  • readme-generation - Generate missing docs
  • naming-enforcement - Fix naming issues

Example​

Input: "Analyze this project structure"

Output:
Score: 72/100 (Grade C)

Issues Found:
- 8 stray files in root
- 5 directories missing README
- 3 naming convention violations
- 2 files with invalid frontmatter

Recommendations:
1. Move stray files to appropriate directories
2. Generate missing READMEs
3. Rename files to follow conventions

Success Output​

When this skill completes successfully, output:

✅ SKILL COMPLETE: file-structure-analysis

Completed:
- [x] Root-level structure checked
- [x] Directory traversal completed
- [x] Naming convention validation finished
- [x] README coverage calculated
- [x] Frontmatter compliance verified
- [x] Analysis report generated

Outputs:
- structure-analysis-report.md (Complete analysis)
- issue-breakdown.json (Categorized issues)
- recommendations.md (Prioritized fixes)

Score: XX/100 (Grade X)

Issue Summary:
- Critical: X issues requiring immediate action
- High: X issues recommended for next sprint
- Medium: X issues for future improvement
- Low: X minor suggestions

Completion Checklist​

Before marking this skill as complete, verify:

  • All directories in scope have been traversed
  • File and directory naming validated against standards
  • README coverage calculated (directories with/without)
  • Frontmatter checked on all markdown files
  • Issues categorized by severity (critical/high/medium/low)
  • Overall compliance score calculated (0-100)
  • Grade assigned (A/B/C/D/F) based on score
  • Recommendations prioritized and actionable
  • Report saved to specified output location

Failure Indicators​

This skill has FAILED if:

  • ❌ Incomplete directory traversal (directories missed)
  • ❌ Score calculation errors (incorrect percentages)
  • ❌ Missing issue categorization (all marked same severity)
  • ❌ No actionable recommendations provided
  • ❌ Report generation failed (no output file)
  • ❌ Standards not referenced (arbitrary validation)
  • ❌ False positives (valid patterns flagged as issues)
  • ❌ README count mismatch (manual count ≠ reported)

When NOT to Use​

Do NOT use this skill when:

  • Actively developing - Structure changes rapidly, analysis becomes stale immediately
  • Initial project setup - No structure exists yet, nothing to analyze
  • Already well-organized - Waste of time if project consistently scores >90%
  • Non-standard projects - External codebases with their own conventions
  • Small single-file projects - Overhead exceeds value for <10 files
  • CI/CD pipeline - Use automated linters instead for continuous validation
  • Quick exploratory work - Temporary repos don't need structure validation

Use these alternatives instead:

  • Active development: Run after feature completion, not during
  • Initial setup: Use project-organization skill to create structure first
  • Well-organized: Quarterly audits sufficient, not daily
  • Non-standard: Adapt analysis to their conventions or skip
  • Small projects: Manual review faster than automation
  • CI/CD: markdownlint, prettier, custom lint rules
  • Exploratory: Skip analysis for throwaway code

Anti-Patterns (Avoid)​

Anti-PatternProblemSolution
Running without standardsArbitrary validation, inconsistent resultsAlways reference official CODITECT standards
Not categorizing severityEverything treated equally, poor prioritiesUse critical/high/medium/low severity levels
Generic recommendations"Fix naming issues" unhelpfulSpecific: "Rename agents/foo.md to agents/foo-agent.md"
No baseline trackingCan't measure improvement over timeSave scores in git history, track trends
Ignoring false positivesWastes time fixing non-issuesValidate samples before bulk fixes
Analysis without actionReport sits unused, no improvements madeSchedule fix sprints immediately after analysis
Over-analyzingHours analyzing 10-file projectUse quick scan for small projects, full for large
Skipping README checkCritical gap: undocumented directoriesAlways include README coverage in analysis
No frontmatter validationMetadata inconsistency across docsValidate YAML frontmatter on all markdown
Running on dirty working treeResults include temporary filesCommit or stash changes before analysis

Principles​

This skill embodies these CODITECT principles:

#1 Recycle → Extend → Re-Use → Create

  • Reuse existing structure analysis scripts and tools
  • Extend standards with project-specific conventions
  • Create reusable analysis patterns for future projects

#2 First Principles Thinking

  • Understand WHY structure matters (discoverability, maintainability, onboarding)
  • Question assumptions: does this standard apply to this project type?
  • Design analysis from user needs (developer experience) up

#3 Keep It Simple

  • Start with quick scan (root level), expand to full if needed
  • Focus on high-impact issues (critical/high) first
  • Clear scoring: 0-100 maps to A-F grades

#5 Eliminate Ambiguity

  • Explicit severity levels (not "bad" or "needs work")
  • Specific issue locations (file path + line number where possible)
  • Quantified scores (72/100) vs vague ("pretty good")

#6 Clear, Understandable, Explainable

  • Report explains WHY each issue matters
  • Standards referenced for every validation rule
  • Recommendations include rationale and examples

#8 No Assumptions

  • Don't assume directory exists; verify before traversing
  • Don't assume naming conventions; validate against standard
  • Don't assume READMEs present; count explicitly

#11 Automate Everything

  • Automated traversal and issue detection
  • Automated scoring and grading
  • Automated report generation

Full Standard: CODITECT-STANDARD-AUTOMATION.md

Version: 1.1.0 | Updated: 2026-01-04 | Quality Standard: SKILL-QUALITY-STANDARD.md v1.0.0