mk-project-organization
Correct file paths, project layout, and naming conventions. Two modes: advisory (return a path) and organize (restructure).
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 16
- Forks
- 3
01 前言 Front Matter
- name
- mk-project-organization
- description
- Correct file paths, project layout, and naming conventions. Two modes: advisory (return a path) and organize (restructure).
02 资源文件 1
- 参考文档references/directory-rules.md2.5 KB
03 SKILL.md 正文
Project Organization
Standardize file locations, naming conventions, and directory structure for projects.
When to Use
- Creating a file and need the correct path
- Organizing existing files after a messy session
- Enforcing naming conventions across the project
- Other skills need to know where to save output (advisory mode)
Explicit: the project-organization skill [targets]
Workflow Integration
Operates in Phase 6 (Reflect) or advisory mode (called by any skill). Output supports the documenter agent.
Modes
| Mode | Trigger | Behavior |
|---|---|---|
| Advisory | Other skills reference this skill | Return correct path + naming for file type |
| Organize | User invokes directly | Scan → propose → confirm → execute |
Process (Organize Mode)
- Scan + categorize — list all files, assign each to directory category per
references/directory-rules.md, check naming conventions - Propose — present changes as from → to table, ask user approval
- Execute + report — move/rename files, create missing directories, list final structure
Process (Advisory Mode)
- Determine file type from context (source? doc? plan? test? asset?)
- Look up correct path from directory categories
- Apply naming rules (timestamped / evergreen / variant)
- Return:
{path}/{name}.{ext}
Output Format
## Project Organization: {scope}
**Mode:** {advisory | organize}
**Files scanned:** {N}
**Issues found:** {N}
### Changes
| From | To | Reason |
|------|------|--------|
| {old path} | {new path} | {rule violated} |
### Final Structure
{tree view of organized directories}
References
| Reference | When to load | Content |
|---|---|---|
| directory-rules.md | Steps 2-4 — categorizing + naming | Directory categories, naming patterns, nesting logic |
Failure Handling
| Failure | Recovery |
|---|---|
| File conflict (target exists) | Ask user: overwrite, rename, or skip |
| Protected path (.git, .env, node_modules) | Skip silently — never touch |
| No files found in target | Report "No files found in {path}" |
Constraints
- Never overwrite existing files without confirmation
- Never touch
.git/,node_modules/,.envfiles - Respect
.gitignorepatterns - Use
mk:prefix conventions for .agents/skills/ directories
Gotchas
- Monorepo package
nameinpackage.jsonand the directory name can diverge silently — a workspace package atpackages/auth-service/with"name": "@company/auth"is referenced by consumers as@company/auth, but path aliases, Docker build contexts, and some bundlers resolve by directory name; mismatch causes "cannot find module" errors that only appear after a fresh install in CI. tsconfig.jsonpath aliases are NOT honored by test runners without separate config —paths: { "@/*": ["src/*"] }intsconfig.jsonresolves intscand Vite but Vitest and Jest use their own module resolvers; tests using@/aliases silently fall through tonode_moduleslookup and fail with "Cannot find module '@/utils'" unlessmoduleNameMapper(Jest) oralias(Vitest) is configured separately.- Circular path aliases break tree-shaking and cause
undefinedat runtime —src/utils/index.tsre-exporting fromsrc/components/which imports fromsrc/utils/creates a circular dependency that bundlers resolve non-deterministically; the symptom is a component that isundefinedwhen imported via the alias but defined when imported by relative path. - Absolute imports (
src/) vs relative imports (../../) inconsistency prevents reliable refactoring — mixing both styles means automated refactoring tools (VS Code "move file",ts-morph) update only the form they recognize; half the import sites break silently on any file move; enforce one style via ESLintimport/no-relative-parent-importsorimport/no-absolute-path. .gitignorepatterns not applying to already-tracked files causesdist/to appear in PRs — ifdist/was committed before being added to.gitignore, git continues tracking it;git rm -r --cached dist/is required to untrack it, and omitting this step means every build output change appears as a diff in PRs.
04 同仓库更多 Skills
mk-worktree
Manages git worktrees for parallel agent isolation: creates parallel/{name}-{timestamp} branches, merges with conflict detection. NOT for user feature branches (use git worktree directly).
mk-workflow-orchestrator
Auto-invoked 7-phase workflow for complex-feature intent; fasttrack mode for pre-approved specs. NOT for explicit single tasks (mk:cook), green-field builds (mk:autobuild), or simple fixes (mk:fix).
mk-web-to-markdown
Fetch a URL and return clean markdown, for arbitrary external pages (blog, RFC, GitHub issue, vendor doc) not covered by mk:docs-finder. Static-only by default; opt-in JS rendering available.
mk-vulnerability-scanner
Vulnerability analysis: OWASP Top 10, current threat landscape, supply chain security, attack surface mapping, risk prioritization. Use for security audits. NOT for STRIDE/CSO infra audits (mk:cso).
mk-vue
Vue 3 authoring/review: components, composables, reactivity, Pinia, Pinia Colada, file routing, forms. Composition API + script setup. Auto-activates on .vue files. Deep review: mk:vue-best-practices.
mk-vue-testing-best-practices
Vue 3 testing best-practices review: Vitest + Vue Test Utils for components, composables, Pinia, Router, async/Suspense, forms, a11y, plus Playwright E2E strategy. Advisory only.