skills/magnus919_agent-skills
1
0
Fork 0
mirror of https://github.com/magnus919/agent-skills.git synced 2026-09-11 19:47:12 +03:00
Code Issues Packages Projects Releases Wiki Activity

fix(cli-builder): align Phase 4 architecture diagram with scripts/ convention

Browse Source 
The "Completed Architecture" diagram in Phase 4 showed the CLI binary at the
skill root, but every other skill in this repo (and the Agent Skills spec)
places executable scripts in a `scripts/` subdirectory.

Changes:
- Replaced ASCII-art two-layer diagram with concrete directory structure
  showing `scripts/servicex-cli` inside the skill directory
- Added Trigger/Execute layer table clarifying the role of each file
- Updated the "Agent opens session" flow to use `scripts/` relative paths
- Added deployment model comparison (scripts/ inside skill vs global PATH)
- Updated the "Installation instructions" entry in What NOT to Put table

Trigger: neopabo on Nous Research Discord
Signed-off-by: Magnus Hedemark <magnus919@pm.me>
This commit is contained in:
Magnus Hedemark
2026-05-22 16:05:53 -04:00
parent 4d929dd85f
commit c949fe4b5d
1 changed files with 32 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
cli-builder/SKILL.md
+32 -12
View File
@@ -351,16 +351,23 @@ A CLI tool that an agent doesn't know exists is useless. The final phase creates
### The Two-Layer Architecture
Your CLI lives in the skill's `scripts/` directory, alongside SKILL.md:
```
SKILL.md (this file) CLI binary (your tool)
───────────────────────── ─────────────────────────
Tells the agent: Provides the agent:
• When to use this tool • --help as schema
• What data to pass • --json as data contract
• What the output means • --dry-run as preview
• Known gotchas & limits • --force as automation bypass
servicex-cli/
├── scripts/
│ └── servicex-cli # Your CLI binary (Phases 1-3)
├── SKILL.md # The skill wrapper (Phase 4)
└── references/ # Supporting documentation
```
The two layers serve distinct roles:
| Layer | File | Purpose |
|-------|------|---------|
| **Trigger** | `SKILL.md` | Tells the agent when to use this tool, what data to pass, what the output means, known gotchas |
| **Execute** | `scripts/servicex-cli` | Provides `--help` as schema, `--json` as data contract, `--dry-run` as preview, `--force` as automation bypass |
The skill **triggers** the tool. The tool **executes** the contract. Neither is complete without the other.
### Frontmatter Conventions
@@ -442,29 +449,42 @@ tool-name get --id abc123 --json
| Don't | Why |
|-------|-----|
| Full flag reference | That's what `--help` is for. Reference it, don't duplicate it. |
| Installation instructions | The CLI is deployed separately — the skill assumes it exists on PATH |
| Installation instructions | For distribution via this repo, the CLI lives in `scripts/` within the skill directory — the skill documents invocation patterns, not setup. For global installs (PATH), deployment is separate. |
| API architecture details | The skill teaches *usage*, not *architecture*. Gotchas are the exception. |
| Every possible subcommand | Cover the 3-5 most common. Agents discover the rest via `--help`. |
### The Completed Architecture
The two-layer pattern follows the [Agent Skills open format](https://agentskills.io) directory structure:
```
servicex-cli/
├── servicex-cli # The CLI binary (built with Phases 1-3)
└── SKILL.md # The skill wrapper (built in Phase 4)
├── scripts/
│ └── servicex-cli # The CLI binary (built with Phases 1-3)
├── SKILL.md # The skill wrapper (built in Phase 4)
└── references/ # Supporting documentation (optional)
Agent opens session:
├── Loads all SKILL.md descriptions at startup
├── User says "check my servicex resources"
├── skill-triggered: "servicex" in user message matches description
│ └── Agent loads skill body
│ ├── Reads "use servicex-cli list --json"
│ ├── Calls servicex-cli list --json
│ ├── Reads "use scripts/servicex-cli list --json"
│ ├── Runs scripts/servicex-cli list --json
│ └── Reads output, tells user
│
Deeper questions → agent reads CLI --help for specifics
```
#### When to use `scripts/` vs global PATH
| Approach | Best for | Cmd invocation |
|----------|----------|----------------|
| **`scripts/` inside skill** | Distribution via this repo — self-contained, portable, format-compliant. The agent references the script by relative path from the skill root. | `scripts/servicex-cli list --json` |
| **Global PATH** | When the CLI is useful beyond this skill (other agents, human users, scripts). Install to `~/.hermes/scripts/` (Hermes) or a system PATH directory. | `servicex-cli list --json` |
The default for this repo is **`scripts/` inside the skill** — it follows the Agent Skills specification for progressive disclosure and keeps the skill self-contained. Add a note in the skill body when the CLI is also available on global PATH for broader use.
### Skill Wrapper Template
See [references/skill-wrapper-example.md](references/skill-wrapper-example.md) for a complete worked example wrapping a hypothetical API CLI, including frontmatter, essential commands, gotchas, and auth wiring documentation.