Skip to content

feat: skills install and llms.txt documentation #147

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bercianor wants to merge 4 commits into
base: develop
Choose a base branch
from
Open

feat: skills install and llms.txt documentation #147

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
42a9a58
feat: skills install and llms.txt documentation
bercianor Jun 3, 2026
9fd39bd
chore: update to a new llms.txt plugin
bercianor Jun 3, 2026
6aa4a8d
fix: add agentic-coders link and beta warning
bercianor Jun 4, 2026
f57821d
Merge branch 'develop' into feat/skill-install-docs
bercianor Jun 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 63 additions & 48 deletions docs/cli/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,25 +66,40 @@ flamingock [global-options] <command> [command-options]

### Global options

| Option | Short | Description |
|--------|-------|-------------|
| `--log-level` | `-l` | Application log level: `debug`, `info`, `warn`, `error` |
| `--quiet` | `-q` | Suppress non-essential output |
| `--no-color` | | Disable colored output |
| `--help` | `-h` | Show help information |
| `--version` | | Show version information |
| Option | Short | Description |
|---------------|--------|---------------------------------------------------------|
| `--log-level` | `-l` | Application log level: `debug`, `info`, `warn`, `error` |
| `--quiet` | `-q` | Suppress non-essential output |
| `--no-color` | | Disable colored output |
| `--help` | `-h` | Show help information |
| `--version` | | Show version information |

Global options are inherited by all subcommands.

### `install-skills`

Install skills from the Flamingock registry. By default, installs all skills to `./.agents/skills`. Use `--agent` to install skills for a specific agent.

| Command | Destination |
|----------------------------------------------------------------------------------------------|----------------------------------------------------------------------|
| `flamingock install-skills` | `./.agents/skills` |
| `flamingock install-skills --agent {claude, github, cursor, opencode, gemini, windsurf, pi}` | `./.{claude, github, cursor, opencode, gemini, windsurf, pi}/skills` |
Comment thread
bercianor marked this conversation as resolved.

:::note
Paths are resolved relative to the directory where you run the command.
:::

Comment thread
bercianor marked this conversation as resolved.
More info at [Using Flamingock with agentic coders](../resources/agentic-coders.md).

### `execute apply`

Apply pending changes by spawning your application JAR.

| Option | Short | Required | Description |
|--------|-------|----------|-------------|
| `--jar` | `-j` | Yes | Path to the application JAR |
| `--java-opt` | `-J` | No | JVM argument for the spawned process (repeatable) |
| `--` | | No | Separator — everything after is passed as application arguments |
| Option | Short | Required | Description |
|--------------|-------|----------|-----------------------------------------------------------------|
| `--jar` | `-j` | Yes | Path to the application JAR |
| `--java-opt` | `-J` | No | JVM argument for the spawned process (repeatable) |
| `--` | | No | Separator — everything after is passed as application arguments |

```bash
# Apply pending changes
Expand All @@ -104,14 +119,14 @@ flamingock execute apply --jar ./my-app.jar -J -Xmx1g -- --spring.profiles.activ

List audit entries from the change history.

| Option | Short | Required | Description |
|--------|-------|----------|-------------|
| `--jar` | `-j` | Yes | Path to the application JAR |
| `--history` | | No | Show full chronological history instead of snapshot |
| `--since` | | No | Filter entries since date (ISO-8601: `yyyy-MM-dd` or `yyyy-MM-ddTHH:mm:ss`) |
| `--extended` | `-e` | No | Show extended information (execution ID, class, method, hostname) |
| `--java-opt` | `-J` | No | JVM argument for the spawned process (repeatable) |
| `--` | | No | Separator — everything after is passed as application arguments |
| Option | Short | Required | Description |
|--------------|-------|----------|-----------------------------------------------------------------------------|
| `--jar` | `-j` | Yes | Path to the application JAR |
| `--history` | | No | Show full chronological history instead of snapshot |
| `--since` | | No | Filter entries since date (ISO-8601: `yyyy-MM-dd` or `yyyy-MM-ddTHH:mm:ss`) |
| `--extended` | `-e` | No | Show extended information (execution ID, class, method, hostname) |
| `--java-opt` | `-J` | No | JVM argument for the spawned process (repeatable) |
| `--` | | No | Separator — everything after is passed as application arguments |

```bash
# Current state (latest per change unit)
Expand All @@ -131,13 +146,13 @@ flamingock audit list --jar ./my-app.jar --extended

Fix audit state for a change with issues. After manually verifying or fixing the state, mark the change as resolved.

| Option | Short | Required | Description |
|--------|-------|----------|-------------|
| `--jar` | `-j` | Yes | Path to the application JAR |
| `--change-id` | `-c` | Yes | Change unit ID to fix |
| `--resolution` | `-r` | Yes | Resolution type: `APPLIED` or `ROLLED_BACK` |
| `--java-opt` | `-J` | No | JVM argument for the spawned process (repeatable) |
| `--` | | No | Separator — everything after is passed as application arguments |
| Option | Short | Required | Description |
|----------------|-------|----------|-----------------------------------------------------------------|
| `--jar` | `-j` | Yes | Path to the application JAR |
| `--change-id` | `-c` | Yes | Change unit ID to fix |
| `--resolution` | `-r` | Yes | Resolution type: `APPLIED` or `ROLLED_BACK` |
| `--java-opt` | `-J` | No | JVM argument for the spawned process (repeatable) |
| `--` | | No | Separator — everything after is passed as application arguments |

```bash
# Mark as successfully applied
Expand All @@ -153,12 +168,12 @@ For detailed workflows on issue resolution, see [Issue resolution](../safety-and

List all change units with inconsistent audit states.

| Option | Short | Required | Description |
|--------|-------|----------|-------------|
| `--jar` | `-j` | Yes | Path to the application JAR |
| `--json` | | No | Output in JSON format |
| `--java-opt` | `-J` | No | JVM argument for the spawned process (repeatable) |
| `--` | | No | Separator — everything after is passed as application arguments |
| Option | Short | Required | Description |
|--------------|-------|----------|-----------------------------------------------------------------|
| `--jar` | `-j` | Yes | Path to the application JAR |
| `--json` | | No | Output in JSON format |
| `--java-opt` | `-J` | No | JVM argument for the spawned process (repeatable) |
| `--` | | No | Separator — everything after is passed as application arguments |

```bash
# List issues in table format
Expand All @@ -172,14 +187,14 @@ flamingock issue list --jar ./my-app.jar --json

Get detailed information about an audit issue.

| Option | Short | Required | Description |
|--------|-------|----------|-------------|
| `--jar` | `-j` | Yes | Path to the application JAR |
| `--change-id` | `-c` | No | Specific change unit ID (shows first issue if omitted) |
| `--guidance` | `-g` | No | Include resolution guidance |
| `--json` | | No | Output in JSON format |
| `--java-opt` | `-J` | No | JVM argument for the spawned process (repeatable) |
| `--` | | No | Separator — everything after is passed as application arguments |
| Option | Short | Required | Description |
|---------------|-------|----------|-----------------------------------------------------------------|
| `--jar` | `-j` | Yes | Path to the application JAR |
| `--change-id` | `-c` | No | Specific change unit ID (shows first issue if omitted) |
| `--guidance` | `-g` | No | Include resolution guidance |
| `--json` | | No | Output in JSON format |
| `--java-opt` | `-J` | No | JVM argument for the spawned process (repeatable) |
| `--` | | No | Separator — everything after is passed as application arguments |

```bash
# Get next priority issue with resolution guidance
Expand All @@ -197,13 +212,13 @@ flamingock issue get --jar ./my-app.jar -c user-change-v2 --json

## Exit codes

| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | Execution error (change failed, process error, etc.) |
| `2` | Usage error (invalid arguments) |
| `126` | JAR not found or not a file |
| `130` | Interrupted (Ctrl+C) |
| Code | Meaning |
|-------|------------------------------------------------------|
| `0` | Success |
| `1` | Execution error (change failed, process error, etc.) |
| `2` | Usage error (invalid arguments) |
| `126` | JAR not found or not a file |
| `130` | Interrupted (Ctrl+C) |

## Example output

Expand Down
79 changes: 79 additions & 0 deletions docs/resources/agentic-coders.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
---
title: Using Flamingock with Agentic Coders
sidebar_position: 50
---

# Using Flamingock with agentic coders
Comment thread
bercianor marked this conversation as resolved.

**Flamingock** is designed to be **agent-ready**. Modern agentic coding assistants — such as **Claude Code**, **Gemini CLI**, and **OpenCode** — can be significantly more productive and accurate when working with Flamingock thanks to our adherence to emerging standards for AI-developer collaboration.
Comment thread
bercianor marked this conversation as resolved.

By providing structured context and specialized skills, Flamingock ensures that AI agents generate setup and change code that is not only syntactically correct but also follows all architectural best practices, naming conventions, and safety patterns.

---

## 🛠 Pillar 1: LLM-optimized documentation (`llms.txt`)

Flamingock documentation is optimized for Large Language Models (LLMs) using the [llms.txt](https://llmstxt.org/) standard. Instead of having an agent crawl dozens of HTML pages, you can provide a single, structured entry point.

We provide two key files at the root of our documentation:

1. **`/llms.txt`**: A concise index of the documentation, providing a high-level overview and links to all relevant sections.
2. **`/llms-full.txt`**: A comprehensive, markdown-formatted file containing the **entire documentation** content. This is the most efficient way to give an agent the full context of Flamingock in a single request.

### How to use it

When starting a session with an agentic coder, point it to these resources to ensure it has the latest information:

```bash
# Example with an agent that supports external context URLs
claude "Create a new Flamingock change to add an index to the users collection. Read the documentation at: https://docs.flamingock.io/llms-full.txt"
```

---

## 🧠 Pillar 2: Agent skills (`agentskills.io`)

:::caution Beta feature
Flamingock Skills are still in **beta**.
:::

Beyond general documentation, Flamingock provides specialized **Skills** following the [agentskills.io](https://agentskills.io/) standard. A skill is a set of machine-readable instructions that teaches an agent exactly how to perform a specific task within the Flamingock ecosystem — without guessing or hallucinating APIs.

All official skills are hosted at: [github.com/flamingock/flamingock-skills](https://github.com/flamingock/flamingock-skills).
Comment thread
bercianor marked this conversation as resolved.

### Installing skills

Skills are installed per project, and you can install all of them using the Flamingock CLI tool:

| Command | Destination |
|----------------------------------------------|----------------------|
| `flamingock install-skills` | `./.agents/skills` |
| `flamingock install-skills --agent claude` | `./.claude/skills` |

@osantana85 osantana85 Jun 15, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would add a specific subcommand for codex, because we are talking about agents and not about paths. If we need to do somethingelse in the future for a specific agent, we should manage codex too.

| `flamingock install-skills --agent github` | `./.github/skills` |
| `flamingock install-skills --agent cursor` | `./.cursor/skills` |
| `flamingock install-skills --agent opencode` | `./.opencode/skills` |
| `flamingock install-skills --agent gemini` | `./.gemini/skills` |
| `flamingock install-skills --agent windsurf` | `./.windsurf/skills` |
| `flamingock install-skills --agent pi` | `./.pi/skills` |

:::note
Paths are resolved relative to the directory where you run the command.
:::

Then commit it to your repository so every developer and every CI agent gets it automatically:

```bash
git add .agents/skills/flamingock-*/
git commit -m "chore: add Flamingock agent skills"
```

Refer to the [Flamingock Skills repository](https://github.com/flamingock/flamingock-skills) for the full list of available skills.

---

## 💎 Benefits of the agentic approach

- **Correctness**: The agent follows the exact Flamingock API — no guessed method names, no invented configuration keys.
- **Consistency**: Every project gets the same setup patterns, regardless of which developer or agent generates them.
- **Safety**: Guards in the skill prevent common mistakes before any code is written.
- **Speed**: From "I need to set up Flamingock" to a working, production-ready configuration in seconds.
28 changes: 26 additions & 2 deletions docusaurus.config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -195,9 +195,33 @@ const config = {
}),
plugins: [
[
"docusaurus-plugin-generate-llms-txt",
'docusaurus-plugin-llms', // https://github.com/rachfop/docusaurus-plugin-llms
{
outputFile: "llms.txt",
generateLLMsTxt: true,
generateLLMsFullTxt: true,
docsDir: 'docs',
includeBlog: true,
excludeImports: true,
removeDuplicateHeadings: true,
generateMarkdownFiles: true,
includeOrder: [
'overview.md',
'get-started/**/*',
'flamingock-library-config/**/*',
'changes/**/*',
'target-systems/**/*',
'audit-stores/**/*',
'safety-and-recovery/**/*',
'templates/**/*',
'frameworks/**/*',
'testing/**/*',
'cli/**/*',
'resources/**/*',
],
includeUnmatchedLast: true,
pathTransformation: {
ignorePaths: ['docs'],
},
},
],
[require.resolve('docusaurus-lunr-search'), {
Expand Down
2 changes: 1 addition & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@
"@mdx-js/react": "^3.0.0",
"clsx": "^2.0.0",
"docusaurus-lunr-search": "^3.6.0",
"docusaurus-plugin-generate-llms-txt": "^0.0.1",
"docusaurus-plugin-llms": "^0.4.0",
"prism-react-renderer": "^2.3.0",
"react": "^19.0.0",
"react-dom": "^19.0.0"
Expand Down
31 changes: 26 additions & 5 deletions yarn.lock
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3433,6 +3433,13 @@ brace-expansion@^1.1.7:
balanced-match "^1.0.0"
concat-map "0.0.1"

brace-expansion@^2.0.2:
version "2.1.1"
resolved "https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-2.1.1.tgz#c68b1c4111c76aae3a6fba55d496cee10c39dad8"
integrity sha512-WR1cURNjuvBLMZBMbqM0UoE+WAfdUcEV1ccD8PVBVOI+Z3ND4+SZbN8RsfT2bMuG1qwz5RFvPukSZm5fF2D5eA==
dependencies:
balanced-match "^1.0.0"

braces@^3.0.3, braces@~3.0.2:
version "3.0.3"
resolved "https://registry.yarnpkg.com/braces/-/braces-3.0.3.tgz#490332f40919452272d55a8480adc0c441358789"
Expand Down Expand Up @@ -4630,12 +4637,14 @@ docusaurus-lunr-search@^3.6.0:
unified "^9.2.2"
unist-util-is "^4.1.0"

docusaurus-plugin-generate-llms-txt@^0.0.1:
version "0.0.1"
resolved "https://registry.yarnpkg.com/docusaurus-plugin-generate-llms-txt/-/docusaurus-plugin-generate-llms-txt-0.0.1.tgz#e2104a73bdf59ea9f576f319e73e7d9c664e6ea8"
integrity sha512-XlUeQ23anYc85I1k9pO61fWcMWcUs8Tx7n3zqIus/1wjZ1mjezm0lOX9jymu9Y2MAi3/YQbDxsfo4kZrMf5q6A==
docusaurus-plugin-llms@^0.4.0:
version "0.4.0"
resolved "https://registry.yarnpkg.com/docusaurus-plugin-llms/-/docusaurus-plugin-llms-0.4.0.tgz#020f00d83459c7feb71c7b6e61774d864336d8ae"
integrity sha512-jYlj2HJ5+gu7oJZuJ83Hk8KlB65YlZZ/7UpHXiL7Qr+qpNBkVocmt2Molc6F3HNr5RqcfhWD/98CvgyNztg/ow==
dependencies:
js-yaml "^4.1.0"
gray-matter "^4.0.3"
minimatch "^9.0.3"
yaml "^2.8.1"

dom-converter@^0.2.0:
version "0.2.0"
Expand Down Expand Up @@ -7321,6 +7330,13 @@ minimatch@^3.1.2:
dependencies:
brace-expansion "^1.1.7"

minimatch@^9.0.3:
version "9.0.9"
resolved "https://registry.yarnpkg.com/minimatch/-/minimatch-9.0.9.tgz#9b0cb9fcb78087f6fd7eababe2511c4d3d60574e"
integrity sha512-OBwBN9AL4dqmETlpS2zasx+vTeWclWzkblfZk7KTA5j3jeOONz/tRCnZomUyvNg83wL5Zv9Ss6HMJXAgL8R2Yg==
dependencies:
brace-expansion "^2.0.2"

minimist@^1.2.0:
version "1.2.8"
resolved "https://registry.yarnpkg.com/minimist/-/minimist-1.2.8.tgz#c1a464e7693302e082a075cee0c057741ac4772c"
Expand Down Expand Up @@ -10230,6 +10246,11 @@ yallist@^3.0.2:
resolved "https://registry.yarnpkg.com/yallist/-/yallist-3.1.1.tgz#dbb7daf9bfd8bac9ab45ebf602b8cbad0d5d08fd"
integrity sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==

yaml@^2.8.1:
version "2.9.0"
resolved "https://registry.yarnpkg.com/yaml/-/yaml-2.9.0.tgz#78274afd93598a1dfdd6130df6a566defcbf9aa4"
integrity sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==

yocto-queue@^1.0.0:
version "1.2.1"
resolved "https://registry.yarnpkg.com/yocto-queue/-/yocto-queue-1.2.1.tgz#36d7c4739f775b3cbc28e6136e21aa057adec418"
Expand Down