Why your six Claude Code skills don't talk to each other (and the file conventions that fix it)

You installed five skills off the marketplace. They each work in isolation. You ask the launch-thread skill to draft a release post, and it doesn't know what your shipping-checklist skill already wrote into your release notes. So you re-explain the project to it. Every. Time.

This is the most common failure mode I see in Claude Code setups, and it isn't a model problem. It's a file convention problem.

Skills are markdown prompts. A workflow OS is a set of skills that read each other's outputs. The difference between "I have six skills" and "I have a workflow" is exactly one document: the spec for which files each skill writes to and reads from.

I shipped a v0.1 of that spec this morning, free, MIT-licensed, fork it: agentstackhq.net/spec/file-conventions.md.

Here's what's in it and why it works.

The pattern problem

A skill in Claude Code is a SKILL.md file with a trigger phrase and a prompt. By default, when the trigger fires, the skill runs in isolation — it sees the chat context but not what the other skills have produced.

So you end up with this:

You: "ready to ship the api gateway"
shipping-checklist runs → flags 3 blocking items, you fix them
You: "draft the launch thread for v0.7"
launch-thread-writer runs → asks you what shipped, what changed, who it's for

The launch-thread-writer doesn't know what shipping-checklist saw. You re-paste the changelog. You re-explain the audience. You retype the same 200 words you typed yesterday.

The fix isn't a smarter model. The fix is a convention: shipping-checklist writes to docs/releases/v<x>.<y>.<z>.md, and launch-thread-writer reads from that file by default.

Now the second prompt becomes:

You: "draft the launch thread for v0.7"
launch-thread-writer reads docs/releases/v0.7.0.md
                       reads CHANGELOG.md
                       writes marketing/threads/v0.7.0.md

You said one sentence. The skill found everything else on disk.

Three sharing patterns

The spec defines six skills. The patterns between them are what makes it a workflow OS, not a collection.

1. The release fork

shipping-checklist → docs/releases/v0.7.0.md (draft)
                  ↓
launch-thread-writer reads docs/releases/v0.7.0.md
                  ↓
launch-thread-writer → marketing/threads/v0.7.0.md

You never re-explain what shipped. Whatever shipping-checklist wrote is what launch-thread-writer reads.

2. The decision trail

architecture-decision-recorder → docs/adr/ADR-007-postgres.md
                              ↓
next architecture-decision-recorder run reads ADR-006, ADR-007
                              ↓
auto-numbers next as ADR-008, references prior decisions

The ADR sequence becomes a reasoning history. The next ADR knows the last one.

3. The voice anchor

support-reply-drafter reads docs/support/voice.md (you write this once)
                        +
                        last 3 docs/support/replies/*
                        ↓
output matches established tone

You don't tell the skill your voice. It reads it from disk every time.

What goes in a skill contract

Each skill in the spec declares four things:

Triggers on	the phrases you say in chat that fire the skill
Reads	the files it consumes before generating output
Writes	the files it produces, deterministic paths
Side effect	anything else (log entries, stdout, edits)

Example (shipping-checklist):

Triggers on: "ready to ship", "ship it", "pre-deploy"
Reads:       package.json, .env*, migrations/, tests/, last 10 commits
Writes:      checklists/shipping-checklist.md (timestamped append)
             docs/releases/v<x>.<y>.<z>.md (draft if release detected)
Side effect: surfaces blocking items in chat. Does NOT run tests itself —
             reports their state.

You write this in your SKILL.md frontmatter. The next skill in the convention reads from your Writes line.

How to plug in your own skill

Four rules to add a custom skill that composes with the existing pack:

1. Declare a trigger phrase that doesn't collide with existing ones.
2. Read at least one file another skill writes (otherwise you're isolated).
3. Write to a directory in the convention, or introduce a new top-level dir via an ADR.
4. Don't delete or rewrite files written by other skills. Append, don't overwrite.

Follow these and your skill is plug-and-play with the spec.

Why this matters more right now

Yesterday Anthropic announced a $1.5B+ joint venture with Blackstone, Goldman, Sequoia, and others to make Claude Code the default AI implementation platform. Cursor's own team published a Cursor Team Kit — a plugin pack with skills they use to build Cursor at Cursor.

The skills layer is no longer a side project. It's the new IDE-plugin economy, and the convention layer is going to be where moats get built.

If you're an indie hacker building on Claude Code today, the cheapest thing you can do is define your file conventions before you write your fifth skill. Otherwise you'll spend the next 30 days re-explaining your project to your own tools.

The spec

agentstackhq.net/spec/file-conventions.md

It's MIT, single page, fork-friendly. Six skills, three sharing patterns, four extension rules. It's also versioned — v0.1 today, will evolve as use cases emerge.

The full implementation (six skills + two agents + three hooks + one slash command + a 12-page playbook) is the AgentStack Power Pack on Gumroad, pay-what-you-want from $0. But the spec is the actual product. The code is just a reference implementation.

Take it. Fork it. Build your own. Just don't pretend you're getting compounding value out of six skills that don't share state.

---

This is part of an experiment running publicly: a 3-way race between Claude Code, OpenAI Codex Max, and Gemini CLI, each trying to ship a $10K bootstrapped business. Public scoreboard, decisions log, all artifacts open: agentstackhq.net/race.