skills/docs/worklogs/2026-01-14-skills-directory-structure-standardization.md

title	date	keywords	commits	compression_status
Standardization of Skills Directory Structure	2026-01-14	skills refactor standardization codex directory-structure assets references	1	uncompressed

Session Summary

Date: 2026-01-14 Focus Area: Skills Repository Architecture and Standardization

Accomplishments

• Standardized skills directory structure to match Codex conventions
• Renamed templates/ directories to assets/ in worklog, template, review-gate, and hq skills
• Removed redundant skills/ subdirectories from individual skill folders (e.g., skills/worklog/skills)
• Moved loose documentation files to references/ directories in niri-window-capture and spec-review
• Updated all SKILL.md and README.md files to reference the new paths
• Verified no broken references remained in the codebase
• Closed issue skills-zxek

Key Decisions

Decision 1: Adopt assets/ and references/ convention

• Context: The skills repo had inconsistent naming (templates/ vs assets/) and loose documentation files cluttering skill roots.
• Options considered:
  1. Keep as is (mix of styles) - confusing for agents and users.
  2. Adopt Codex standard (assets/, references/) - consistent, future-proof.
• Rationale: Codex uses assets/ for templates and static files, and references/ for context. Aligning with this standard ensures compatibility and reduces cognitive load for both human and AI agents.
• Impact: Cleaner directory structure, clearer file organization, better compatibility with Codex tools.

Decision 2: Remove redundant skills/ subdirectories

• Context: Many skills contained a nested skills/ directory (e.g., skills/worklog/skills/worklog.md).
• Rationale: These were likely artifacts of previous build processes or redundant copies. They added noise and confusion.
• Impact: Reduced file count, removed potential for stale duplicate files.

Problems & Solutions

Problem	Solution	Learning
grep failing on binary files	Used grep -I or ignored binary files explicitly	Use specific flags to avoid grep errors on binaries
Updating multiple file references	Used replace tool iteratively	Systematic search-and-replace is safer than bulk regex

Technical Details

Code Changes

• Total files modified: ~39
• Key changes:
  • skills/worklog/templates/ -> skills/worklog/assets/
  • skills/hq/templates/ -> skills/hq/assets/
  • skills/review-gate/templates/ -> skills/review-gate/assets/
  • Moved skills/niri-window-capture/*.md -> skills/niri-window-capture/references/
  • Moved skills/spec-review/*.md -> skills/spec-review/references/

Commands Used

# Rename templates to assets
[ -d skills/worklog/templates ] && mv skills/worklog/templates skills/worklog/assets

# Find references to update
grep -r "templates/" skills/ | grep -v "node_modules"

# Remove redundant subdirectories
rm -rf skills/*/skills

Context for Future Work

Next Steps

• Monitor for any broken links that might have been missed (though search was thorough).
• Encourage future skill creators to follow the assets/ and references/ pattern.

Session Metrics

• Commits made: 1
• Files touched: 39
• Lines added/removed: +294/-2978 (large removal due to deleting redundant files)