Designing the shared/ Directory: How I Organized Rules, Skills, and Workflows for AI to Reference
When Rule Files Start to Pile Up
As harness engineering progresses, the number of files AI references grows. What started as a single file becomes unwieldy as content is added, and it becomes difficult to know where specific information lives.
The problem I ran into while building this site was that CLAUDE.md was getting too long. Prohibition rules, content writing guidelines, deployment procedures, review standards—keeping all of this in one file meant AI was processing a large amount of text at the start of every session, and important rules were getting buried. When I wanted AI to read only the rules relevant to a specific task, everything was mixed together in one place.
The shared/ Directory Structure
To address this, I moved all files AI references into a directory called shared/ and organized them by role.
To use an analogy of onboarding a new team member:
shared/rules/→ “Company policies and prohibitions”shared/skills/→ “Step-by-step guides for each type of work”shared/workflow/→ “Multi-step process flows”
These three categories are the foundation of the structure.
rules
This is a collection of files covering prohibitions and project policies—what AI must not do and what approach this project takes. Examples include content-i18n.md (language policy for content), no-ui-regression.md (the scope of prohibited UI changes), and build-and-deploy.md (deployment constraints). Rules are written as direct policies rather than conditional guidance so that AI can apply them without ambiguity.
skills
These are step-by-step guides for specific types of tasks. They are the equivalent of procedural manuals a new team member would look up when unsure how to do something. Examples include blog-writing/SKILL.md (how to write blog articles) and editorial-review/SKILL.md (the review procedure). When AI begins a task, it refers to the relevant skill file and works through the steps described there.
workflow
These files describe multi-step process flows that span more than one type of work. While a rule or skill covers a single policy or procedure, a workflow describes the sequence of a larger operation from start to finish. An example would be: write the article, translate it, conduct a review, and publish.
What Changes When Files Are Organized This Way
Organizing files by role makes it clearer to AI where to find the information relevant to a current task.
CLAUDE.md can reference specific files rather than containing everything: “For content language requirements, see shared/rules/content-i18n.md.” This keeps CLAUDE.md concise while all the detail remains organized under shared/.
When a rule needs to be updated, it is also clear which file to change. When everything is in one large file, a single change can unintentionally affect other content in ways that are hard to trace.
Notes on Maintaining the Structure
The most important thing when designing the shared/ directory is deciding the placement criteria upfront. Without clear criteria, the classification becomes ambiguous as files accumulate.
The criteria I use:
- “Must not do” or “project policy” →
rules/ - “Steps for this type of task” →
skills/(placed as SKILL.md in a subdirectory) - “Multi-step process from start to finish” →
workflow/
When in doubt, I start by placing something in rules/ and reorganize later if needed.
Summary
When the files AI references grow in number, organizing them by role is effective. Using three categories—shared/rules/ for prohibitions and policies, shared/skills/ for task procedures, and shared/workflow/ for multi-step process flows—makes it easier for AI to find the relevant information and keeps CLAUDE.md concise. When files are organized, AI behavior becomes more consistent and maintaining and updating rules becomes more manageable.