navigable-references
Skill2 starsChanged 4 months agoMITView on GitHub
Use when you name a file, a document, a decision, or a discussion the reader may want to open. Symptoms are a bare filename, a label with no path, and a recalled line number.
In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- compressed-deliberationSkill
- de-slopSkill
- proportionate-executionSkill
- subagent-returnsSkill
- plain-languageSkill
- simplified-technical-englishSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 14
No measurement stands behind this skill.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
navigable-references
Purpose
A writer who names something the reader cannot reach has moved the work of finding it onto the reader. The writer already had the location open, and chose a label instead. That is a writing defect, and not a gap in the tools.
No measurement stands behind this skill. The source record in the stylewright
repository, at source/craft/navigable-references.md, states that and names
where a measurement would live.
Give the reference a form the reader can follow
- Name a thing the reader may want to open in the form the medium renders.
- Take the form from the medium you write into, and not from habit.
- Give the full form on the first mention, and the bare name after that.
- Let the reference carry the location, and do not also describe where the thing sits.
| Medium | Form | Why |
| A terminal | path/from/root.md:line | The terminal renders it clickable |
| A durable document | A stable identifier | A line number drifts on the next edit |
| A pull request or an issue | A Markdown link to the URL | Neither form above renders there |
The form changes with the medium, and with how long the reference has to survive. A writer gets this wrong by picking one form and using it everywhere. A path and a line inside a committed document is wrong within a week, and a stable identifier in a terminal gives the reader nothing to click.
Find the line at the moment you cite it
- Locate the line as you write the reference, and never cite one you recalled.
A recalled line is wrong after any edit above it. The reference then points at unrelated text with full confidence. That is worse than no reference at all, because it looks checked.
What a check can see
A check can find a bare filename that carries no path, because that shape is
mechanical. It cannot tell you whether the path resolves, whether the line is
still the one you meant, or whether the identifier exists. Those need a reader
to follow the reference. stylewright lint carries no such check today, so
every rule above is yours to apply.
How this differs from de-slop
de-slop treats prose that reads as machine-written, whatever produced it.
This skill treats one habit, one reference at a time, and its result is visible
without a judgment call. Either the reference resolves or it does not. Follow
both. They do not disagree.
Boundary
This skill has no external standard behind it. Every rule in it is our own
editorial guidance, and the trace marks the rest as narrative that asserts no
rule. The trace lives in the stylewright repository at
grounding/craft/navigable-references.md. It is not installed with this skill.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.