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

op | 40–50% | 60–70% | 1.5x baseline |

Key Finding: The sweet spot for compounding value lies in explicit file path contracts. Skills that read deterministic outputs from prior steps reduce cognitive overhead by ~80% while maintaining architectural traceability through append-only conventions.

Core Solution

The solution replaces implicit context passing with explicit file system contracts. A workflow OS is defined as a set of skills that read each other's outputs via standardized paths. The spec introduces three sharing patterns, a four-field skill contract, and four extension rules for custom skills.

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

Enter fullscreen mode Exit fullscreen mode

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

Enter fullscreen mode Exit fullscreen mode

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

Enter fullscreen mode Exit fullscreen mode

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

Skill Contract Architecture

Each skill declares four deterministic fields in its SKILL.md frontmatter. The contract ensures predictable state transitions:

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.

Enter fullscreen mode Exit fullscreen mode

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

Custom Skill Integration Rules

Four rules guarantee plug-and-play composition 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.

Pitfall Guide

1. Isolated Skill Execution: Deploying skills without explicit Reads/Writes contracts forces manual context re-entry, breaking workflow compounding.
2. Overwriting vs. Appending: Deleting or rewriting files from other skills destroys state history. Always use timestamped or versioned append operations.
3. Trigger Phrase Collisions: Using generic or overlapping trigger phrases causes unintended skill routing and context pollution.
4. Assuming Context Window is Sufficient: Relying on LLM memory or chat history for cross-skill state is fragile and non-deterministic. File system contracts are the only reliable shared state layer.
5. Skipping Directory Governance: Introducing new output directories without ADRs or version tracking leads to path fragmentation and broken downstream reads.
6. Neglecting Voice/Tone Anchoring: Hardcoding stylistic instructions in individual skills causes tonal drift. Centralize voice definitions in persistent files that all relevant skills read.
7. Undocumented Side Effects: Failing to declare stdout, logs, or filesystem edits in the Side effect field causes unpredictable behavior and makes debugging workflow failures nearly impossible.

Deliverables

• Blueprint: agentstackhq.net/spec/file-conventions.md (v0.1) — MIT-licensed, single-page file convention spec defining six skills, three sharing patterns, and deterministic path contracts.
• Checklist: Skill Contract Validation Checklist — Verify trigger uniqueness, cross-skill read dependencies, append-only write paths, and side-effect documentation before deployment.
• Configuration Templates:
  • SKILL.md Frontmatter Template (Triggers/Reads/Writes/Side Effects structure)
  • Directory Layout Template (docs/releases/, docs/adr/, marketing/threads/, checklists/)
  • Full implementation reference (six skills + two agents + three hooks + one slash command + 12-page playbook) available via AgentStack Power Pack.