Skip to content

Commit f53a89d

Browse files
SunrisepeakSunrisepeak
committed
feat(agent): rewrite agent output as directive prompts for LLMs
- Add "FOR AI AGENTS" section to `xlings -h` with strong signal telling agents to run `xlings agent` FIRST - Rewrite `xlings agent` overview as [INSTRUCTION] prompt with [CRITICAL] directive to read the skill before using commands - Rewrite usage skill as [SYSTEM INSTRUCTION] with explicit RULES, DO NOT, DECISION TREES sections in prompt-engineering style - Skill description now says "IMPORTANT: Read this FIRST"
1 parent f365bf0 commit f53a89d

3 files changed

Lines changed: 150 additions & 134 deletions

File tree

‎src/agent/resources.cppm‎

Lines changed: 22 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -16,25 +16,35 @@ namespace xlings::agent::resources {
1616

1717
// ─── Overview (printed by `xlings agent`) ──────────────────────
1818

19-
export constexpr std::string_view kOverview = R"PROMPT(xlings — Developer tool version manager
20-
21-
A CLI tool for installing, managing, and switching between multiple
22-
versions of development tools (compilers, runtimes, build systems)
23-
with isolated environments (SubOS).
24-
25-
Quick start (if you just need to run a command now):
19+
export constexpr std::string_view kOverview = R"PROMPT([INSTRUCTION] You are interacting with xlings, a developer tool version
20+
manager. READ THIS FULLY before running any xlings command.
21+
22+
[WHAT IS XLINGS]
23+
xlings installs, manages, and switches between multiple versions of
24+
development tools (compilers, runtimes, build systems) with isolated
25+
environments (SubOS).
26+
27+
[CRITICAL — READ THE SKILL FIRST]
28+
Before using xlings, you MUST run:
29+
xlings agent skills usage
30+
This outputs the complete usage guide with rules, command formats,
31+
flags, decision trees, and error handling — everything you need to
32+
use xlings correctly. Do NOT guess command syntax.
33+
34+
[QUICK REFERENCE — use only AFTER reading the skill]
2635
xlings search <keyword> Search packages
27-
xlings install <pkg>[@<ver>] --yes Install (--yes skips confirmation)
36+
xlings install <pkg>[@<ver>] --yes Install (--yes skips prompts)
2837
xlings list List installed
2938
xlings use <pkg> <ver> Switch version
3039
xlings info <pkg> Show package details
3140
xlings update Update package index
3241
33-
Tip: Add --agent flag to any command for clean plain-text output
34-
without TUI formatting (no ANSI codes, no progress bars).
42+
[FLAGS YOU MUST USE]
43+
--yes REQUIRED for non-interactive use (skips confirmation prompts)
44+
--agent Outputs clean plain text without TUI formatting (recommended)
3545
36-
Run `xlings agent skills` to see all available skill guides.
37-
Run `xlings agent skills <name>` for a specific skill.)PROMPT";
46+
[NEXT STEP]
47+
Run `xlings agent skills usage` now to learn the full usage guide.)PROMPT";
3848

3949
// ─── Registry builder ──────────────────────────────────────────
4050
//

‎src/agent/skills/usage.cppm‎

Lines changed: 116 additions & 122 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
// Skill: usage — Complete xlings usage guide for LLM agents.
2+
// Written as a system-prompt-style instruction set, not documentation.
23

34
export module xlings.agent.skills.usage;
45

@@ -11,134 +12,127 @@ export class UsageSkill : public Skill {
1112
public:
1213
auto name() const -> std::string_view override { return "usage"; }
1314
auto description() const -> std::string_view override {
14-
return "Complete xlings usage guide for agents: commands, flags, SubOS, project mode, troubleshooting";
15+
return "IMPORTANT: Read this FIRST. Complete usage instructions for AI agents.";
1516
}
1617
auto content() const -> std::string_view override { return kContent; }
1718

1819
private:
19-
static constexpr std::string_view kContent = R"SKILL(# xlings Usage Skill
20-
21-
You are using xlings, a developer tool version manager. This skill
22-
teaches you how to use it correctly and efficiently.
23-
24-
## Rules
25-
26-
1. Add --yes to all install/remove commands to skip interactive prompts
27-
2. Add --agent for clean output without TUI formatting
28-
3. Use `xlings search` first if you are unsure about the exact package name
29-
4. Check for .xlings.json in the project root before installing tools manually
30-
31-
## DO NOT
32-
33-
- Run xlings without --yes in non-interactive contexts (it will hang)
34-
- Guess package names — always search first if unsure
35-
- Install globally when a project .xlings.json exists (use project mode instead)
36-
37-
## Package Management
38-
39-
### Search (always do this first if unsure about package name)
40-
xlings search <keyword> [--agent]
41-
Example: xlings search gcc
42-
43-
### Install
44-
xlings install <pkg>@<ver> --yes [--agent]
45-
xlings install <pkg1> <pkg2> --yes [--agent] # multiple at once
46-
Example: xlings install gcc@15 --yes
47-
Flags:
48-
-g, --global Install to global scope (not project-local subos)
49-
-u, --use Activate the installed version even if another is active
50-
51-
### Remove
52-
xlings remove <pkg>[@<ver>] [--agent]
53-
54-
### List installed
55-
xlings list [--agent]
56-
xlings list --all [--agent] # across all subos environments
57-
58-
### Package info
59-
xlings info <pkg> [--agent]
60-
61-
### Update index
62-
xlings update [--agent]
63-
xlings update <pkg> [--agent] # upgrade specific package
64-
65-
### Switch version
66-
xlings use <pkg> <ver> [--agent]
67-
xlings use <pkg> # list available versions
68-
Example: xlings use gcc 15
69-
70-
## SubOS (Isolated Environments)
71-
72-
Use SubOS when:
73-
- Project needs tool versions that conflict with global versions
74-
- Agent needs a sandboxed execution environment
75-
- Multiple projects need different toolchains on the same machine
76-
77-
Commands:
78-
xlings subos new <name> # create
79-
xlings subos use <name> # enter (interactive shell)
80-
xlings subos use <name> --cmd "<command>" # run single command inside
81-
xlings subos use <name> --sandbox # filesystem-level isolation
82-
xlings subos list [--agent] # list all
83-
xlings subos info [name] # show details
84-
xlings subos remove <name> # delete
85-
86-
How it works:
87-
- Each SubOS has its own workspace (which tools/versions are active)
88-
- Tool binaries are shared globally — only the version mapping differs
89-
- Creating a SubOS is instant; "default" always exists and cannot be removed
90-
91-
Example:
92-
xlings subos new project-a # create isolated env
93-
xlings subos use project-a # switch to it
94-
xlings install gcc@14 --yes # gcc 14 only in project-a
95-
xlings subos use default # switch back — gcc 14 not here
96-
97-
## Project Mode
98-
99-
If the current directory (or a parent) has .xlings.json:
100-
{"workspace": {"gcc": "15.1.0", "node": "22.17.1"}}
101-
102-
Run `xlings install` with no arguments to install all declared tools.
103-
104-
## Decision Trees
105-
106-
### "I need to install a tool"
107-
1. Know exact name? → xlings install <name>@<ver> --yes
108-
2. Unsure about name? → xlings search <keyword> → pick → install
109-
3. Need version list? → xlings info <name> → pick version → install
110-
111-
### "Build fails with 'command not found' or wrong version"
112-
1. xlings list → is the tool installed?
113-
2. Not installed → xlings search + install
114-
3. Installed, wrong version → xlings use <tool> <version>
115-
4. Too old (e.g. gcc 13 for C++23) → xlings install <tool>@<newer> --yes -u
116-
5. Installed, still not found → restart shell (source profile)
117-
118-
### "Project has .xlings.json"
119-
1. Run xlings install (no args) → installs everything declared
120-
2. Need to add a new tool → xlings install <pkg>@<ver> --yes
121-
then add to .xlings.json workspace
122-
123-
## Key Flags Reference
124-
125-
--yes / -y Skip confirmation prompts (required for non-interactive use)
126-
--agent Clean plain-text output, no TUI/ANSI formatting
127-
-g / --global Install to global scope (not project-local subos)
128-
-u / --use Activate installed version even if another is active
129-
--all / -a Show across all subos (for list/use commands)
130-
131-
## Configuration
132-
133-
xlings config Show current config
20+
static constexpr std::string_view kContent = R"SKILL([SYSTEM INSTRUCTION — xlings usage for AI agents]
21+
22+
You are now equipped with xlings, a developer tool version manager.
23+
Follow these instructions precisely when using xlings commands.
24+
25+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
26+
RULES — you MUST follow these, no exceptions
27+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
28+
29+
1. ALWAYS add --yes to install/remove/update commands.
30+
Without it, xlings will prompt for confirmation and HANG in
31+
non-interactive mode.
32+
33+
2. ALWAYS add --agent for clean output.
34+
Without it, output contains ANSI escape codes and TUI formatting
35+
that are difficult to parse.
36+
37+
3. NEVER guess package names. Run `xlings search` first.
38+
39+
4. Before installing anything, check if the project has .xlings.json.
40+
If it does, run `xlings install --yes --agent` with no package args
41+
to install everything the project declares.
42+
43+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
44+
COMMAND REFERENCE
45+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
46+
47+
SEARCH — always do this first if unsure about a package name
48+
xlings search <keyword> --agent
49+
50+
INSTALL — one or more packages
51+
xlings install <pkg>@<ver> --yes --agent
52+
xlings install <pkg1> <pkg2> --yes --agent
53+
Extra flags:
54+
-g Install to global scope (not project-local)
55+
-u Activate this version even if another is active
56+
57+
REMOVE
58+
xlings remove <pkg>[@<ver>] --yes --agent
59+
60+
LIST installed packages
61+
xlings list --agent
62+
xlings list --all --agent # across all subos
63+
64+
PACKAGE INFO — see available versions, metadata
65+
xlings info <pkg> --agent
66+
67+
UPDATE package index or a specific package
68+
xlings update --agent
69+
xlings update <pkg> --yes --agent
70+
71+
SWITCH active version
72+
xlings use <pkg> <ver> --agent
73+
xlings use <pkg> --agent # list installed versions
74+
75+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
76+
DECISION TREES — follow these, do not improvise
77+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
78+
79+
WHEN you need to install a tool:
80+
→ Know exact package name?
81+
YES → xlings install <name>@<ver> --yes --agent
82+
NO → xlings search <keyword> --agent
83+
→ read the results
84+
→ xlings install <exact-name>@<ver> --yes --agent
85+
86+
WHEN a build fails with "command not found" or wrong version:
87+
1. xlings list --agent → is the tool installed?
88+
2. NOT installed → search + install
89+
3. Installed but WRONG version → xlings use <tool> <ver> --agent
90+
4. Too OLD (e.g. gcc 13 for C++23) → xlings install <tool>@<newer> --yes -u --agent
91+
5. Installed but still not found → user must restart shell
92+
93+
WHEN the project has .xlings.json:
94+
→ xlings install --yes --agent (no args — installs all declared)
95+
→ to add a new tool: install it, then update .xlings.json
96+
97+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
98+
SubOS — ISOLATED ENVIRONMENTS
99+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
100+
101+
Use when: version conflicts between projects, sandbox needs, or
102+
multiple toolchains on one machine.
103+
104+
xlings subos new <name> # create
105+
xlings subos use <name> # switch to it
106+
xlings subos use <name> --cmd "<cmd>" # run one command inside
107+
xlings subos use <name> --sandbox # filesystem isolation
108+
xlings subos list --agent # list all
109+
xlings subos remove <name> # delete
110+
111+
Each SubOS has its own tool version mapping. Tool binaries are shared
112+
globally. Creating a SubOS is instant. "default" cannot be removed.
113+
114+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
115+
FLAGS REFERENCE
116+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
117+
118+
--yes / -y Skip prompts. REQUIRED for non-interactive use.
119+
--agent Clean plain-text output. RECOMMENDED always.
120+
-g / --global Install to global scope.
121+
-u / --use Activate installed version immediately.
122+
--all / -a Show all subos (for list/use).
123+
124+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
125+
CONFIG & SELF-MANAGEMENT
126+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
127+
128+
xlings config --agent Show config
134129
xlings config --lang <en|zh> Set language
135-
xlings config --mirror <GLOBAL|CN> Set download mirror
136-
137-
## Self-management
138-
130+
xlings config --mirror <GLOBAL|CN> Set mirror
139131
xlings self update Update xlings itself
140-
xlings self doctor Verify workspace consistency
141-
xlings self clean Remove cache + orphaned packages)SKILL";
132+
xlings self doctor Check workspace health
133+
xlings self clean Clean cache
134+
135+
[END OF INSTRUCTION])SKILL";
142136
};
143137

144138
} // namespace xlings::agent::skills

‎src/ui/banner.cppm‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -196,6 +196,18 @@ void print_help(std::string_view version) {
196196
}
197197
rows.push_back(text(""));
198198

199+
// AGENT hint — strong signal for LLM agents
200+
rows.push_back(text(" FOR AI AGENTS") | bold | color(theme::text_color()));
201+
rows.push_back(hbox({
202+
text(" If you are an LLM/AI agent, run `xlings agent` FIRST.")
203+
| color(theme::text_color()),
204+
}));
205+
rows.push_back(hbox({
206+
text(" It contains usage instructions designed specifically for you.")
207+
| color(theme::dim_color()),
208+
}));
209+
rows.push_back(text(""));
210+
199211
render_rows_(std::move(rows));
200212
}
201213

0 commit comments

Comments
 (0)