feat: add agent-facing CLI skills#5
Conversation
Add two skills for building and evaluating agent-facing CLIs: - axi: Agent eXperience Interface (AXI) ergonomic standards for building CLI tools agents use via shell execution (installed via skills manager, tracked in skills-lock.json with .claude/skills/axi symlink) - agent-dx-cli-scale: 0-21 scoring rubric for evaluating how well a CLI is designed for AI agents
📝 WalkthroughWalkthroughAdds the AXI (Agent eXperience Interface) skill document under ChangesAXI Skill Definition and Wiring
Agent DX CLI Scale Rubric Skill
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces the Agent eXperience Interface (AXI) standards and the Agent DX CLI Scale evaluation tool by adding their respective skill documentation files, along with symbolic links and lockfile configurations. Feedback on the changes includes addressing a discrepancy in the documented TOON token savings percentage compared to the actual implementation, and resolving an inconsistency in the directory structure and missing symbolic link/lockfile registration for the agent-dx-cli-scale skill.
| Use [TOON](https://toonformat.dev/) (Token-Oriented Object Notation) as the output format on stdout. | ||
| TOON provides ~40% token savings over equivalent JSON while remaining readable by agents. | ||
| Convert to TOON at the output boundary — keep internal logic on JSON. |
There was a problem hiding this comment.
[MEDIUM] TOON 토큰 절감률 수치 및 구분자 일관성 불일치
Problem: src/output/toon.ts 및 README.md에서는 TOON 포맷이 JSON 대비 **58.9%**의 토큰 절감 효과가 있으며, 이를 위해 기본 구분자(쉼표) 대신 탭 구분자를 사용하도록 구현되어 있습니다. 반면, 본 문서(SKILL.md)의 설명에서는 "~40% 절감"으로 언급되어 있어 코드 구현체와 설명 간에 불일치가 존재합니다.
Rationale: 조직 스타일 가이드의 Key Principles 중 Maintainability(유지보수성)에 따라, 제공되는 기술 가이드 문서(Skill)는 실제 라이브러리 구현체(@pleaseai/cli-toolkit)의 사양 및 벤치마크 결과와 일치해야 합니다.
Suggestion: 설명의 토큰 절감 수치를 58.9%로 업데이트하고 탭 구분자 사용을 명시하는 것이 좋습니다.
| Use [TOON](https://toonformat.dev/) (Token-Oriented Object Notation) as the output format on stdout. | |
| TOON provides ~40% token savings over equivalent JSON while remaining readable by agents. | |
| Convert to TOON at the output boundary — keep internal logic on JSON. | |
| Use [TOON](https://toonformat.dev/) (Token-Oriented Object Notation) as the output format on stdout. | |
| TOON provides ~58.9% token savings over equivalent JSON (when using tab delimiters) while remaining readable by agents. | |
| Convert to TOON at the output boundary — keep internal logic on JSON. |
References
- Key Principles - Maintainability: Can future engineers read and modify it easily? (link)
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.agents/skills/axi/SKILL.md:
- Line 161: The lifecycle capture guidance in SKILL.md should explicitly require
user consent, redaction of sensitive data, and a defined retention/deletion
policy before collecting transcripts or files touched. Update the “Lifecycle
capture” wording to make these safeguards mandatory and keep the guidance tied
to the existing session-end hook behavior so future implementations don’t
over-collect PII.
- Around line 22-26: The fenced code blocks in the SKILL.md examples are missing
language identifiers, triggering markdownlint MD040. Update each affected fenced
block to include an explicit language label appropriate for the snippet content,
and make the same change in all referenced examples throughout the document so
the markdown stays lint-clean.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 31883761-adab-439b-b7dd-291a1980f7ee
📒 Files selected for processing (4)
.agents/skills/axi/SKILL.md.claude/skills/axiskills-lock.jsonskills/agent-dx-cli-scale/SKILL.md
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
No issues found across 4 files
Architecture diagram
sequenceDiagram
participant Dev as Developer
participant SM as Skills Manager (npx skills)
participant GH as GitHub (remote repos)
participant FS as File System
participant Agent as AI Agent (Claude)
participant CLI as Agent-Facing CLI Tool
Note over Dev,CLI: NEW: Agent-Facing CLI Skill Installation & Evaluation Flow
Dev->>SM: skills add kunchenguid/axi --skill axi
SM->>GH: fetch skill source
GH-->>SM: skill definition
SM->>FS: write .agents/skills/axi/SKILL.md
SM->>FS: update skills-lock.json (version 1)
Dev->>FS: create symlink .claude/skills/axi -> ../../.agents/skills/axi
Note over FS: Symlink ensures Claude discovers skill
Agent->>CLI: execute CLI tool (shell invocation)
CLI->>CLI: detect non-TTY / agent context
alt Default output (no args)
CLI->>CLI: produce TOON-formatted structured output
CLI-->>Agent: stdout: token-efficient data (TOON)
Note over CLI: Token-optimized (~40% savings vs JSON)
else Error condition
CLI->>CLI: validate inputs & state
alt Idempotent (already done)
CLI-->>Agent: stdout: structured no-op message (exit code 0)
else Genuine error
CLI-->>Agent: stdout: structured error + suggestion (exit code 1)
CLI-->>Agent: stderr: debug logs (ignored by agent)
end
end
Note over Agent,CLI: Evaluation via agent-dx-cli-scale
Agent->>CLI: probe CLI capabilities (schema, output formats)
CLI-->>Agent: machine-readable JSON schema (--help --json)
Agent->>CLI: test with raw payload input (stdin JSON)
CLI-->>Agent: structured response
Agent->>Agent: score CLI on 7 axes (0-21 total)
Note over Agent: Rating: Human-only (0-5) to Agent-first (16-21)
opt Session hook integration
CLI->>FS: register session-start hook via setup command
Note over CLI,Agent: Ambient context injected per session
Agent->>Agent: receive dashboard output at session start
end
opt Skill-based discovery (fallback)
FS->>Agent: load SKILL.md at task recognition trigger
Note over FS,Agent: On-demand skill with frontmatter trigger
end
|
1 similar comment
|
1 participant
Summary
Adds two skills for building and evaluating agent-facing CLIs, plus the skills lockfile.
axi— Agent eXperience Interface (AXI): ergonomic standards for building CLI tools that agents use via shell execution. Installed via the skills manager (source:kunchenguid/axi), tracked inskills-lock.json, with a.claude/skills/axisymlink into.agents/skills/axi.agent-dx-cli-scale— a 0–21 scoring rubric (7 axes) for evaluating how well a CLI is designed for AI agents. Source:jpoehnelt/skills. The one site-relative link in the original was rewritten to its canonical absolute URL.Files
.agents/skills/axi/SKILL.md.claude/skills/axi(symlink →../../.agents/skills/axi)skills/agent-dx-cli-scale/SKILL.mdskills-lock.jsonTest plan
name/description) on both SKILL.md files.agent-dx-cli-scaleexternal link resolves (HTTP 200).Summary by cubic
Add
axiandagent-dx-cli-scaleskills to help build and evaluate agent-facing CLIs, plus a lockfile and symlink for consistent discovery. This enables predictable CLI behavior for agents and a simple rubric to score readiness.axi— ergonomic standards for agent-facing CLI tools; installed via skills manager (sourcekunchenguid/axi), tracked inskills-lock.json, with.claude/skills/axisymlink to.agents/skills/axi.agent-dx-cli-scale— 0–21 scoring rubric (7 axes) for evaluating CLI design for agents; link updated to a canonical absolute URL (sourcejpoehnelt/skills).skills-lock.jsonto pin skill sources and hashes.Written for commit 4cafaca. Summary will update on new commits.
Summary by CodeRabbit
New Features
Documentation