extracting-ai-context

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.

Extracting AI Context from workflow-kotlin

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.

Prerequisites

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.

Quick Start

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.

Agent-Specific Setup

Claude Code Users

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

Other Agents

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

Custom Project Layouts

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.

What Gets Extracted

Skills

Version-matched skills from workflow-kotlin JARs on your classpath:

• create-workflow — Creating StatefulWorkflow and StatelessWorkflow classes
• workflow-testing — Unit testing with testRender / RenderTester
• workflow-integration-testing — Integration testing with renderForTest / WorkflowTurbine
• extracting-ai-context — This skill (self-referential for future re-runs)

AGENTS.md

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 -->

Updating After a Version Bump

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.

Preview Mode

See what would be extracted without writing files:

./gradlew extractAiContext --preview

Gitignore

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.

Troubleshooting

No skills extracted

• Verify the plugin is applied: check for com.squareup.workflow1.ai-context in your build file
• Ensure workflow-kotlin dependencies are on the classpath (e.g., workflow-core, workflow-testing)
• Run with --info for verbose output: ./gradlew extractAiContext --info

Skills are outdated

• Re-run ./gradlew extractAiContext after updating your workflow-kotlin version
• Check that Gradle resolved the new version: ./gradlew dependencies | grep workflow