trigger-docs

An experiment to replicate Vercel's agents-md approach for Trigger.dev documentation.

TL;DR: We couldn't prove it works better than inline docs.

The Experiment

We spent days building and testing a compressed documentation approach for AI coding assistants, inspired by Vercel's @next/codemod agents-md tool.

What We Built

Compressed index (~1.2KB) injected into CLAUDE.md
Local MDX files in .trigger-docs/ read on-demand
Instruction prompt to force retrieval-led reasoning

What We Tested

6 configurations against 8 Trigger.dev v4 API tasks:

Rank	Configuration	Pass Rate	Turns	Efficiency
1	inline-docs	93%	2.5	37.2
2	trigger-docs	79%	6.4	12.3
3	mcp-only	71%	2.4	29.6
4	skills-only	70%	8.1	8.6
5	skills-mcp	56%	5.0	11.2
6	baseline	25%	3.0	8.3

The Finding

Inline docs won decisively. Simply pasting Trigger.dev's llms-full.txt into CLAUDE.md outperformed:

Our compressed index approach (-14%)
The official Trigger.dev MCP server (-22%)
Claude Code skills (-23%)
Combined skills+MCP (-37%)

Why We Think It Failed

Overhead: Compressed approach adds ~6 turns to read MDX files
Selection problem: Model must choose WHICH file to read (often wrong)
MCP latency: Tool calls add time and the model doesn't query effectively
Skill invocation: Skills add 5-6 turns of overhead before getting docs

Repository Structure

trigger-docs/
├── docs/
│ └── STRATEGY-GUIDE.md # Framework for building agents-md tools
├── test-suite/
│ ├── fixtures/ # Test configurations (6 approaches)
│ ├── results/ # Raw evaluation data
│ ├── src/ # Test runner code
│ └── README.md # Test methodology
└── README.md # This file

Test Cases

We targeted Trigger.dev v4+ APIs likely absent from LLM training data:

API	Why It's a Good Test
`batchTriggerAndWait()`	New batch API with Result object pattern
`wait.forToken()`	Token-based wait patterns
`metadata.parent`	Hierarchical metadata access
`debounce` option	Recently added triggering option
`queue()` shared queues	Cross-task queue definitions
`idempotencyKeys.create()`	Scoped idempotency patterns

Running the Tests

cd test-suite
pnpm install
pnpm test# Run all configurations
pnpm test:report # Generate comparison report

Our Conclusion

If you have <1200 lines of documentation:

Just paste them inline.

The engineering effort to build compressed indexes, MCP servers, or skills may not be worth the quality loss.

Open Questions

Does this work better on Sonnet/Opus vs Haiku?
Is Next.js docs structured differently than Trigger.dev?
Did Vercel test against different baseline conditions?
Is ~800 lines of context really that expensive?

References

License

MIT

trigger-docs

An experiment to replicate Vercel's agents-md approach for Trigger.dev documentation.

TL;DR: We couldn't prove it works better than inline docs.

The Experiment

We spent days building and testing a compressed documentation approach for AI coding assistants, inspired by Vercel's @next/codemod agents-md tool.

What We Built

Compressed index (~1.2KB) injected into CLAUDE.md
Local MDX files in .trigger-docs/ read on-demand
Instruction prompt to force retrieval-led reasoning

What We Tested

6 configurations against 8 Trigger.dev v4 API tasks:

Rank	Configuration	Pass Rate	Turns	Efficiency
1	inline-docs	93%	2.5	37.2
2	trigger-docs	79%	6.4	12.3
3	mcp-only	71%	2.4	29.6
4	skills-only	70%	8.1	8.6
5	skills-mcp	56%	5.0	11.2
6	baseline	25%	3.0	8.3

The Finding

Inline docs won decisively. Simply pasting Trigger.dev's llms-full.txt into CLAUDE.md outperformed:

Our compressed index approach (-14%)
The official Trigger.dev MCP server (-22%)
Claude Code skills (-23%)
Combined skills+MCP (-37%)

Why We Think It Failed

Overhead: Compressed approach adds ~6 turns to read MDX files
Selection problem: Model must choose WHICH file to read (often wrong)
MCP latency: Tool calls add time and the model doesn't query effectively
Skill invocation: Skills add 5-6 turns of overhead before getting docs

Repository Structure

trigger-docs/
├── docs/
│ └── STRATEGY-GUIDE.md # Framework for building agents-md tools
├── test-suite/
│ ├── fixtures/ # Test configurations (6 approaches)
│ ├── results/ # Raw evaluation data
│ ├── src/ # Test runner code
│ └── README.md # Test methodology
└── README.md # This file

Test Cases

We targeted Trigger.dev v4+ APIs likely absent from LLM training data:

API	Why It's a Good Test
`batchTriggerAndWait()`	New batch API with Result object pattern
`wait.forToken()`	Token-based wait patterns
`metadata.parent`	Hierarchical metadata access
`debounce` option	Recently added triggering option
`queue()` shared queues	Cross-task queue definitions
`idempotencyKeys.create()`	Scoped idempotency patterns

Running the Tests

cd test-suite
pnpm install
pnpm test# Run all configurations
pnpm test:report # Generate comparison report

Our Conclusion

If you have <1200 lines of documentation:

Just paste them inline.

The engineering effort to build compressed indexes, MCP servers, or skills may not be worth the quality loss.

Open Questions

Does this work better on Sonnet/Opus vs Haiku?
Is Next.js docs structured differently than Trigger.dev?
Did Vercel test against different baseline conditions?
Is ~800 lines of context really that expensive?

References

License

MIT

trigger-docs

An experiment to replicate Vercel's agents-md approach for Trigger.dev documentation.

TL;DR: We couldn't prove it works better than inline docs.

The Experiment

We spent days building and testing a compressed documentation approach for AI coding assistants, inspired by Vercel's @next/codemod agents-md tool.

What We Built

Compressed index (~1.2KB) injected into CLAUDE.md
Local MDX files in .trigger-docs/ read on-demand
Instruction prompt to force retrieval-led reasoning

What We Tested

6 configurations against 8 Trigger.dev v4 API tasks:

Rank	Configuration	Pass Rate	Turns	Efficiency
1	inline-docs	93%	2.5	37.2
2	trigger-docs	79%	6.4	12.3
3	mcp-only	71%	2.4	29.6
4	skills-only	70%	8.1	8.6
5	skills-mcp	56%	5.0	11.2
6	baseline	25%	3.0	8.3

The Finding

Inline docs won decisively. Simply pasting Trigger.dev's llms-full.txt into CLAUDE.md outperformed:

Our compressed index approach (-14%)
The official Trigger.dev MCP server (-22%)
Claude Code skills (-23%)
Combined skills+MCP (-37%)

Why We Think It Failed

Overhead: Compressed approach adds ~6 turns to read MDX files
Selection problem: Model must choose WHICH file to read (often wrong)
MCP latency: Tool calls add time and the model doesn't query effectively
Skill invocation: Skills add 5-6 turns of overhead before getting docs

Repository Structure

trigger-docs/
├── docs/
│ └── STRATEGY-GUIDE.md # Framework for building agents-md tools
├── test-suite/
│ ├── fixtures/ # Test configurations (6 approaches)
│ ├── results/ # Raw evaluation data
│ ├── src/ # Test runner code
│ └── README.md # Test methodology
└── README.md # This file

Test Cases

We targeted Trigger.dev v4+ APIs likely absent from LLM training data:

API	Why It's a Good Test
`batchTriggerAndWait()`	New batch API with Result object pattern
`wait.forToken()`	Token-based wait patterns
`metadata.parent`	Hierarchical metadata access
`debounce` option	Recently added triggering option
`queue()` shared queues	Cross-task queue definitions
`idempotencyKeys.create()`	Scoped idempotency patterns

Running the Tests

cd test-suite
pnpm install
pnpm test# Run all configurations
pnpm test:report # Generate comparison report

Our Conclusion

If you have <1200 lines of documentation:

Just paste them inline.

The engineering effort to build compressed indexes, MCP servers, or skills may not be worth the quality loss.

Open Questions

Does this work better on Sonnet/Opus vs Haiku?
Is Next.js docs structured differently than Trigger.dev?
Did Vercel test against different baseline conditions?
Is ~800 lines of context really that expensive?

References

License

MIT

trigger-docs

An experiment to replicate Vercel's agents-md approach for Trigger.dev documentation.

TL;DR: We couldn't prove it works better than inline docs.

The Experiment

We spent days building and testing a compressed documentation approach for AI coding assistants, inspired by Vercel's @next/codemod agents-md tool.

What We Built

Compressed index (~1.2KB) injected into CLAUDE.md
Local MDX files in .trigger-docs/ read on-demand
Instruction prompt to force retrieval-led reasoning

What We Tested

6 configurations against 8 Trigger.dev v4 API tasks:

Rank	Configuration	Pass Rate	Turns	Efficiency
1	inline-docs	93%	2.5	37.2
2	trigger-docs	79%	6.4	12.3
3	mcp-only	71%	2.4	29.6
4	skills-only	70%	8.1	8.6
5	skills-mcp	56%	5.0	11.2
6	baseline	25%	3.0	8.3

The Finding

Inline docs won decisively. Simply pasting Trigger.dev's llms-full.txt into CLAUDE.md outperformed:

Our compressed index approach (-14%)
The official Trigger.dev MCP server (-22%)
Claude Code skills (-23%)
Combined skills+MCP (-37%)

Why We Think It Failed

Overhead: Compressed approach adds ~6 turns to read MDX files
Selection problem: Model must choose WHICH file to read (often wrong)
MCP latency: Tool calls add time and the model doesn't query effectively
Skill invocation: Skills add 5-6 turns of overhead before getting docs

Repository Structure

trigger-docs/
├── docs/
│ └── STRATEGY-GUIDE.md # Framework for building agents-md tools
├── test-suite/
│ ├── fixtures/ # Test configurations (6 approaches)
│ ├── results/ # Raw evaluation data
│ ├── src/ # Test runner code
│ └── README.md # Test methodology
└── README.md # This file

Test Cases

We targeted Trigger.dev v4+ APIs likely absent from LLM training data:

API	Why It's a Good Test
`batchTriggerAndWait()`	New batch API with Result object pattern
`wait.forToken()`	Token-based wait patterns
`metadata.parent`	Hierarchical metadata access
`debounce` option	Recently added triggering option
`queue()` shared queues	Cross-task queue definitions
`idempotencyKeys.create()`	Scoped idempotency patterns

Running the Tests

cd test-suite
pnpm install
pnpm test# Run all configurations
pnpm test:report # Generate comparison report

Our Conclusion

If you have <1200 lines of documentation:

Just paste them inline.

The engineering effort to build compressed indexes, MCP servers, or skills may not be worth the quality loss.

Open Questions

Does this work better on Sonnet/Opus vs Haiku?
Is Next.js docs structured differently than Trigger.dev?
Did Vercel test against different baseline conditions?
Is ~800 lines of context really that expensive?

References

License

MIT

trigger-docs

An experiment to replicate Vercel's agents-md approach for Trigger.dev documentation.

TL;DR: We couldn't prove it works better than inline docs.

The Experiment

We spent days building and testing a compressed documentation approach for AI coding assistants, inspired by Vercel's @next/codemod agents-md tool.

What We Built

Compressed index (~1.2KB) injected into CLAUDE.md
Local MDX files in .trigger-docs/ read on-demand
Instruction prompt to force retrieval-led reasoning

What We Tested

6 configurations against 8 Trigger.dev v4 API tasks:

Rank	Configuration	Pass Rate	Turns	Efficiency
1	inline-docs	93%	2.5	37.2
2	trigger-docs	79%	6.4	12.3
3	mcp-only	71%	2.4	29.6
4	skills-only	70%	8.1	8.6
5	skills-mcp	56%	5.0	11.2
6	baseline	25%	3.0	8.3

The Finding

Inline docs won decisively. Simply pasting Trigger.dev's llms-full.txt into CLAUDE.md outperformed:

Our compressed index approach (-14%)
The official Trigger.dev MCP server (-22%)
Claude Code skills (-23%)
Combined skills+MCP (-37%)

Why We Think It Failed

Overhead: Compressed approach adds ~6 turns to read MDX files
Selection problem: Model must choose WHICH file to read (often wrong)
MCP latency: Tool calls add time and the model doesn't query effectively
Skill invocation: Skills add 5-6 turns of overhead before getting docs

Repository Structure

trigger-docs/
├── docs/
│ └── STRATEGY-GUIDE.md # Framework for building agents-md tools
├── test-suite/
│ ├── fixtures/ # Test configurations (6 approaches)
│ ├── results/ # Raw evaluation data
│ ├── src/ # Test runner code
│ └── README.md # Test methodology
└── README.md # This file

Test Cases

We targeted Trigger.dev v4+ APIs likely absent from LLM training data:

API	Why It's a Good Test
`batchTriggerAndWait()`	New batch API with Result object pattern
`wait.forToken()`	Token-based wait patterns
`metadata.parent`	Hierarchical metadata access
`debounce` option	Recently added triggering option
`queue()` shared queues	Cross-task queue definitions
`idempotencyKeys.create()`	Scoped idempotency patterns

Running the Tests

cd test-suite
pnpm install
pnpm test# Run all configurations
pnpm test:report # Generate comparison report

Our Conclusion

If you have <1200 lines of documentation:

Just paste them inline.

The engineering effort to build compressed indexes, MCP servers, or skills may not be worth the quality loss.

Open Questions

Does this work better on Sonnet/Opus vs Haiku?
Is Next.js docs structured differently than Trigger.dev?
Did Vercel test against different baseline conditions?
Is ~800 lines of context really that expensive?

References

License

MIT

trigger-docs

An experiment to replicate Vercel's agents-md approach for Trigger.dev documentation.

TL;DR: We couldn't prove it works better than inline docs.

The Experiment

We spent days building and testing a compressed documentation approach for AI coding assistants, inspired by Vercel's @next/codemod agents-md tool.

What We Built

Compressed index (~1.2KB) injected into CLAUDE.md
Local MDX files in .trigger-docs/ read on-demand
Instruction prompt to force retrieval-led reasoning

What We Tested

6 configurations against 8 Trigger.dev v4 API tasks:

Rank	Configuration	Pass Rate	Turns	Efficiency
1	inline-docs	93%	2.5	37.2
2	trigger-docs	79%	6.4	12.3
3	mcp-only	71%	2.4	29.6
4	skills-only	70%	8.1	8.6
5	skills-mcp	56%	5.0	11.2
6	baseline	25%	3.0	8.3

The Finding

Inline docs won decisively. Simply pasting Trigger.dev's llms-full.txt into CLAUDE.md outperformed:

Our compressed index approach (-14%)
The official Trigger.dev MCP server (-22%)
Claude Code skills (-23%)
Combined skills+MCP (-37%)

Why We Think It Failed

Overhead: Compressed approach adds ~6 turns to read MDX files
Selection problem: Model must choose WHICH file to read (often wrong)
MCP latency: Tool calls add time and the model doesn't query effectively
Skill invocation: Skills add 5-6 turns of overhead before getting docs

Repository Structure

trigger-docs/
├── docs/
│ └── STRATEGY-GUIDE.md # Framework for building agents-md tools
├── test-suite/
│ ├── fixtures/ # Test configurations (6 approaches)
│ ├── results/ # Raw evaluation data
│ ├── src/ # Test runner code
│ └── README.md # Test methodology
└── README.md # This file

Test Cases

We targeted Trigger.dev v4+ APIs likely absent from LLM training data:

API	Why It's a Good Test
`batchTriggerAndWait()`	New batch API with Result object pattern
`wait.forToken()`	Token-based wait patterns
`metadata.parent`	Hierarchical metadata access
`debounce` option	Recently added triggering option
`queue()` shared queues	Cross-task queue definitions
`idempotencyKeys.create()`	Scoped idempotency patterns

Running the Tests

cd test-suite
pnpm install
pnpm test# Run all configurations
pnpm test:report # Generate comparison report

Our Conclusion

If you have <1200 lines of documentation:

Just paste them inline.

The engineering effort to build compressed indexes, MCP servers, or skills may not be worth the quality loss.

Open Questions

Does this work better on Sonnet/Opus vs Haiku?
Is Next.js docs structured differently than Trigger.dev?
Did Vercel test against different baseline conditions?
Is ~800 lines of context really that expensive?

References

License

MIT

trigger-docs

An experiment to replicate Vercel's agents-md approach for Trigger.dev documentation.

TL;DR: We couldn't prove it works better than inline docs.

The Experiment

We spent days building and testing a compressed documentation approach for AI coding assistants, inspired by Vercel's @next/codemod agents-md tool.

What We Built

Compressed index (~1.2KB) injected into CLAUDE.md
Local MDX files in .trigger-docs/ read on-demand
Instruction prompt to force retrieval-led reasoning

What We Tested

6 configurations against 8 Trigger.dev v4 API tasks:

Rank	Configuration	Pass Rate	Turns	Efficiency
1	inline-docs	93%	2.5	37.2
2	trigger-docs	79%	6.4	12.3
3	mcp-only	71%	2.4	29.6
4	skills-only	70%	8.1	8.6
5	skills-mcp	56%	5.0	11.2
6	baseline	25%	3.0	8.3

The Finding

Inline docs won decisively. Simply pasting Trigger.dev's llms-full.txt into CLAUDE.md outperformed:

Our compressed index approach (-14%)
The official Trigger.dev MCP server (-22%)
Claude Code skills (-23%)
Combined skills+MCP (-37%)

Why We Think It Failed

Overhead: Compressed approach adds ~6 turns to read MDX files
Selection problem: Model must choose WHICH file to read (often wrong)
MCP latency: Tool calls add time and the model doesn't query effectively
Skill invocation: Skills add 5-6 turns of overhead before getting docs

Repository Structure

trigger-docs/
├── docs/
│ └── STRATEGY-GUIDE.md # Framework for building agents-md tools
├── test-suite/
│ ├── fixtures/ # Test configurations (6 approaches)
│ ├── results/ # Raw evaluation data
│ ├── src/ # Test runner code
│ └── README.md # Test methodology
└── README.md # This file

Test Cases

We targeted Trigger.dev v4+ APIs likely absent from LLM training data:

API	Why It's a Good Test
`batchTriggerAndWait()`	New batch API with Result object pattern
`wait.forToken()`	Token-based wait patterns
`metadata.parent`	Hierarchical metadata access
`debounce` option	Recently added triggering option
`queue()` shared queues	Cross-task queue definitions
`idempotencyKeys.create()`	Scoped idempotency patterns

Running the Tests

cd test-suite
pnpm install
pnpm test# Run all configurations
pnpm test:report # Generate comparison report

Our Conclusion

If you have <1200 lines of documentation:

Just paste them inline.

The engineering effort to build compressed indexes, MCP servers, or skills may not be worth the quality loss.

Open Questions

Does this work better on Sonnet/Opus vs Haiku?
Is Next.js docs structured differently than Trigger.dev?
Did Vercel test against different baseline conditions?
Is ~800 lines of context really that expensive?

References

License

MIT

trigger-docs

An experiment to replicate Vercel's agents-md approach for Trigger.dev documentation.

TL;DR: We couldn't prove it works better than inline docs.

The Experiment

We spent days building and testing a compressed documentation approach for AI coding assistants, inspired by Vercel's @next/codemod agents-md tool.

What We Built

Compressed index (~1.2KB) injected into CLAUDE.md
Local MDX files in .trigger-docs/ read on-demand
Instruction prompt to force retrieval-led reasoning

What We Tested

6 configurations against 8 Trigger.dev v4 API tasks:

Rank	Configuration	Pass Rate	Turns	Efficiency
1	inline-docs	93%	2.5	37.2
2	trigger-docs	79%	6.4	12.3
3	mcp-only	71%	2.4	29.6
4	skills-only	70%	8.1	8.6
5	skills-mcp	56%	5.0	11.2
6	baseline	25%	3.0	8.3

The Finding

Inline docs won decisively. Simply pasting Trigger.dev's llms-full.txt into CLAUDE.md outperformed:

Our compressed index approach (-14%)
The official Trigger.dev MCP server (-22%)
Claude Code skills (-23%)
Combined skills+MCP (-37%)

Why We Think It Failed

Overhead: Compressed approach adds ~6 turns to read MDX files
Selection problem: Model must choose WHICH file to read (often wrong)
MCP latency: Tool calls add time and the model doesn't query effectively
Skill invocation: Skills add 5-6 turns of overhead before getting docs

Repository Structure

trigger-docs/
├── docs/
│ └── STRATEGY-GUIDE.md # Framework for building agents-md tools
├── test-suite/
│ ├── fixtures/ # Test configurations (6 approaches)
│ ├── results/ # Raw evaluation data
│ ├── src/ # Test runner code
│ └── README.md # Test methodology
└── README.md # This file

Test Cases

We targeted Trigger.dev v4+ APIs likely absent from LLM training data:

API	Why It's a Good Test
`batchTriggerAndWait()`	New batch API with Result object pattern
`wait.forToken()`	Token-based wait patterns
`metadata.parent`	Hierarchical metadata access
`debounce` option	Recently added triggering option
`queue()` shared queues	Cross-task queue definitions
`idempotencyKeys.create()`	Scoped idempotency patterns

Running the Tests

cd test-suite
pnpm install
pnpm test# Run all configurations
pnpm test:report # Generate comparison report

Our Conclusion

If you have <1200 lines of documentation:

Just paste them inline.

The engineering effort to build compressed indexes, MCP servers, or skills may not be worth the quality loss.

Name		Name	Last commit message	Last commit date
docs		docs
test-suite		test-suite
.gitignore		.gitignore
README.md		README.md
package.json		package.json

Name		Name	Last commit message	Last commit date
docs		docs
test-suite		test-suite
.gitignore		.gitignore
README.md		README.md
package.json		package.json

Name		Name	Last commit message	Last commit date
docs		docs
test-suite		test-suite
.gitignore		.gitignore
README.md		README.md
package.json		package.json

Name		Name	Last commit message	Last commit date
docs		docs
test-suite		test-suite
.gitignore		.gitignore
README.md		README.md
package.json		package.json

Name		Name	Last commit message	Last commit date
docs		docs
test-suite		test-suite
.gitignore		.gitignore
README.md		README.md
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation

trigger-docs

The Experiment

What We Built

What We Tested

The Finding

Why We Think It Failed

Repository Structure

Test Cases

Running the Tests

Our Conclusion

Open Questions

References

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

trigger-docs

The Experiment

What We Built

What We Tested

The Finding

Why We Think It Failed

Repository Structure

Test Cases

Running the Tests

Our Conclusion

Open Questions

References

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

trigger-docs

The Experiment

What We Built

What We Tested

The Finding

Why We Think It Failed

Repository Structure

Test Cases

Running the Tests

Our Conclusion

Open Questions

References

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Latest commit

History