| name | pointer-directories |
| model | sonnet |
| description | Produces a provenance determination — pointer or gap — for empty or apparently incomplete directories, with a documented rationale and recommended action. Use when: "this directory is empty", "missing SKILL.md", "coverage metric shows a gap", "why is this directory here with nothing in it", "before creating content to fill an apparent void". |
| category | system-health |
| triggers | ["this directory is empty","missing SKILL.md","coverage metric shows a gap","why is this directory here with nothing in it","before creating content to fill an apparent void"] |
| tier | 1 |
| agents | ["primary"] |
| tool_dependencies | ["file_system"] |
| inputs | [{"name":"directory_path","type":"string","description":"Path to the empty or apparently incomplete directory to evaluate","required":true}] |
| outputs | [{"name":"provenance_determination","type":"string","description":"Provenance determination — pointer or gap — with documented rationale and recommended action"}] |
Pointer Directories
Philosophy
Empty directories are not failures of the system. They are signals. In well-designed registries, an empty directory often means: "The content you're looking for exists elsewhere by design." The instinct to fill every gap produces duplication and masks the actual provenance of content.
Before creating content, understand why something is empty. This distinction separates accidental incompleteness from intentional reference architecture.
When to Use
- You encounter empty directories during a registry audit or reorganization
- A coverage metric shows "gaps" that nobody has reported as problems
- You find a skill, component, or module in a registry with no local content
- A project registry reports missing SKILL.md, README, or component files
- You're about to create content to fill an apparent void
- You're building changelog entries and need to account for "missing" content
Workflow
1. Identify the Empty Directory
Locate the directory that appears incomplete. Note its location and expected content type (skill, component, configuration, etc.).
2. Ask the Provenance Question
"Is this directory a pointer or a gap?"
A pointer is intentional. A gap is accidental. You need to know which one before proceeding.
3. Check Three Levels
Search for the content at other levels:
- Source Level: Original authoring location (e.g., dojo-genesis/skills/)
- System-Installed Level: Deployed to runtime (e.g., .skills/skills/, system packages)
- Platform Level: Provided by host platform (e.g., Cowork system skills, external dependencies)
4. Determine Status
- Found at another level? → It's a pointer. Document the provenance.
- Found nowhere? → It's a gap. Create content or mark for later.
- Unclear? → Ask the team or check the changelog.
5. Document Your Finding
If it's a pointer:
- Record which level holds the authoritative content
- Add an entry to the changelog explaining the provenance
- Consider whether a symlink, reference, or comment in the empty directory would help future maintainers
If it's a gap:
- Decide whether to create content now or defer
- If deferring, add a note explaining why the gap exists
Best Practices
Verify before Creating: Always check multiple locations before assuming content is missing. Empty directories are often intentional.
