// Extracts and manages AI context (skills, AGENTS.md) from workflow-kotlin library JARs. Use when setting up AI tooling for a workflow-kotlin project, updating skills after a library version change, or configuring agent-specific directories.
| name | extracting-ai-context |
| description | Extracts and manages AI context (skills, AGENTS.md) from workflow-kotlin library JARs. Use when setting up AI tooling for a workflow-kotlin project, updating skills after a library version change, or configuring agent-specific directories. |
Manages the extraction of version-matched AI skills and AGENTS.md context from workflow-kotlin library JARs into the correct locations for your AI coding agent.
The project must apply the workflow-kotlin AI context Gradle plugin:
// build.gradle / build.gradle.kts
plugins {
id("com.squareup.workflow1.ai-context") version "<workflow-version>"
}
The default destination is the project where the plugin is applied: skills go to
.agents/skills/, and workflow-kotlin guidance is merged into AGENTS.md.
Run the extraction task — this is the primary command:
./gradlew extractAiContext
This extracts all skills to .agents/skills/ and merges workflow-kotlin guidance
into AGENTS.md. This works out of the box for Amp, Cursor, Codex, GitHub Copilot,
Gemini CLI, and OpenCode.
Claude Code uses .claude/skills/ instead of .agents/skills/. To support both:
./gradlew extractAiContext --tools=amp,claude-code
Then create a CLAUDE.md symlink so Claude Code picks up the guidance:
ln -sf AGENTS.md CLAUDE.md
echo "CLAUDE.md" >> .gitignore
The --tools flag accepts any agent name from the Agent Skills standard.
Common options:
| Agent | Flag | Skills Directory |
|---|---|---|
| Amp, Cursor, Codex, Copilot, Gemini CLI | amp (default) | .agents/skills/ |
| Claude Code | claude-code | .claude/skills/ |
| Goose | goose | .goose/skills/ |
| Windsurf | windsurf | .windsurf/skills/ |
| Roo Code | roo | .roo/skills/ |
Multiple agents: --tools=amp,claude-code,goose
If the consuming project keeps AI context somewhere else, configure the plugin:
aiContext {
// Base directory for relative skills directories.
outputDirectory.set(layout.projectDirectory)
// File that receives the workflow-kotlin AGENTS.md injection block.
agentsFile.set(layout.projectDirectory.file("AGENTS.md"))
// Standard agent mappings. Defaults to listOf("amp"), which writes .agents/skills/.
tools.set(listOf("amp", "claude-code"))
// Exact skills directories for custom layouts. Overrides tools when set.
skillsDirectories.set(listOf(".agents/skills", ".claude/skills"))
}
Use --preview before writing files when adopting the plugin in an existing repository.
Version-matched skills from workflow-kotlin JARs on your classpath:
The root workflow-kotlin project guide is merged into your AGENTS.md using
injection markers. Your existing content is preserved — the injected block is
clearly delimited:
<!-- workflow-kotlin-AGENTS-injection:START -->
... workflow-kotlin guidance ...
<!-- workflow-kotlin-AGENTS-injection:END -->
When you update your workflow-kotlin dependency version, re-run the extraction to get version-matched skills and guidance:
./gradlew extractAiContext
The injection markers in AGENTS.md ensure the old content is cleanly replaced.
Skills in .agents/skills/ are overwritten with the new versions.
See what would be extracted without writing files:
./gradlew extractAiContext --preview
Add extracted skill directories to .gitignore since they're generated from JARs:
# Extracted AI context (generated by extractAiContext task)
.agents/skills/create-workflow/
.agents/skills/workflow-testing/
.agents/skills/workflow-integration-testing/
.agents/skills/extracting-ai-context/
Do NOT gitignore AGENTS.md — it contains your project-specific content
alongside the injected workflow-kotlin block.
com.squareup.workflow1.ai-context in your build fileworkflow-core, workflow-testing)--info for verbose output: ./gradlew extractAiContext --info./gradlew extractAiContext after updating your workflow-kotlin version./gradlew dependencies | grep workflowCreate Square Workflow classes (StatefulWorkflow or StatelessWorkflow). Use when creating workflows, implementing state machines, handling async operations with Workers, or when user mentions "new workflow", "workflow", "state machine", or "StatefulWorkflow".
Create Square Workflow classes (StatefulWorkflow or StatelessWorkflow). Use when creating workflows, implementing state machines, handling async operations with Workers, or when user mentions "new workflow", "workflow", "state machine", or "StatefulWorkflow".
Write integration tests for Workflows using renderForTest and WorkflowTurbine. Use when testing full workflow runtime behavior, async operations, state changes over time, output emissions, multi-step user flows, or when user mentions "integration test", "renderForTest", or "WorkflowTurbine".
Write unit tests for StatefulWorkflow and StatelessWorkflow using testRender and RenderTester. Use for workflow unit testing, render testing, expectWorker, expectWorkflow, action verification, or WorkflowOutput assertions.