# Extracting AI Context

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

- Skill: `square/extracting-ai-context` (Agent Skill)
- Install (CLI): `npx skillmds@latest add square/extracting-ai-context`
- Raw SKILL.md: https://api.skillmd.com/api/skills/square/extracting-ai-context/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: square (https://skillmd.com/u/square)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/square/extracting-ai-context

---


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

```groovy
// 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:

```bash
./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:

```bash
./gradlew extractAiContext --tools=amp,claude-code
```

Then create a `CLAUDE.md` symlink so Claude Code picks up the guidance:

```bash
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:

```kotlin
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:

```bash
./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:

```bash
./gradlew extractAiContext --preview
```

## Gitignore

Add extracted skill directories to `.gitignore` since they're generated from JARs:

```gitignore
# 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`