living-artifacts
Skill0 starsChanged 6 months agoMITView on GitHub
Apply when producing any markdown artifact for someone else (or future-you) to read — READMEs, analysis documents, Confluence pages, status reports, troubleshooting write-ups, skill content, conversation summaries, ticket descriptions, post-mortems, snapshots of system state, or any document that contains concrete current-state values. Defines the "snapshot + reproducer" rule (every static value must be paired with the command/query/script that regenerates it), the single-source-of-truth rule (reference canonical homes instead of duplicating values), and fact-vs-assumption marking. Trigger keywords include writing or producing or creating or drafting a README, analysis, Confluence page, status update, summary, snapshot, current state, documenting data, posting findings, file tree, port number, version number, table count, or any concrete value that may drift over time.
In this repository13 other files it gives its agents.
- change-consistencySkill
- engineer-agentic-aiSkill
- format-markdownSkill
- information-representation-designSkill
- messaging-frameworkSkill
- python-testingSkill
- relevance-first-information-designSkill
- reviewable-branch-diffsSkill
- review-ready-codeSkill
- securitySkill
- software-designSkill
- swe-methodSkill
- thoughts-to-artifactSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 7 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
When producing any markdown artifact, every static snapshot of state must be paired with the command, query, or script that regenerates it.
- Distinctive: line 33
When a value already has a canonical home, reference the source instead of duplicating the value in the artifact.
- Distinctive: line 55
Use relative paths from the markdown file's location.
- Distinctive: line 70
Before publishing, scan every concrete value and ask:
- Distinctive: line 73
If not, is the reproducer next to it?
- Distinctive: line 74
If the reader runs the reproducer, will they get the same value?
- Distinctive: line 76
If not, the artifact is incomplete.
≈ “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
Living Artifacts
When producing any markdown artifact, every static snapshot of state must be paired with the command, query, or script that regenerates it. The reader must be able to re-derive the value later without guessing where it came from.
What Counts As A Snapshot
Anything likely to drift between writing and reading time:
- File trees, directory listings, project layouts
- Port numbers, hostnames, URLs, file paths
- Version numbers, deployed commits, image tags
- Row counts, table contents, API response bodies
- Lists of users, repos, tables, services, env vars
- "Currently failing tests" or other status snapshots
- Configuration values that have a canonical home elsewhere
- Counts and aggregates
The Pattern
For each snapshot, include nearby:
- The reproducer first — exact command, query, or script that produces the value.
- The snapshot — clearly framed as a time-of-writing view, not eternal truth.
- A drift caveat — a short note that the value may have changed and can be refreshed with the reproducer.
Single Source Of Truth
When a value already has a canonical home, reference the source instead of duplicating the value in the artifact.
| Bad | Good |
| Hardcoded port in docs | Reference the env var or config that defines it |
| Listing names manually in a README | Point to the directory or generated listing |
| Hardcoded git SHA | Command that resolves the SHA at read time |
| API field list copied into docs | Command that introspects the live API |
File References Must Be Clickable
Whenever a markdown artifact mentions a concrete file path, wrap it in a markdown link so readers can jump to it and broken links surface drift quickly.
Apply this to:
- Source files
- Config files
- Sibling docs
- Scripts
- Skill files
- Generated artifacts the reader should inspect
Use relative paths from the markdown file's location. Do not link placeholders, globs, or path-like CLI fragments inside code blocks.
Facts Vs Assumptions
- Facts are verifiable now and should have a reproducer.
- Assumptions are not currently verifiable and must be marked explicitly.
Separate measured facts from interpretations so readers can tell what was observed versus inferred.
Audience Targeting
Setup READMEs are for end users. Contributor docs and AGENTS.md are for maintainers. Put the right level of detail in the right home.
Self-Check
Before publishing, scan every concrete value and ask:
- Will this still be correct in three months?
- If not, is the reproducer next to it?
- If the reader runs the reproducer, will they get the same value?
If not, the artifact is incomplete.
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.