Skill-management gaps and ambient context for agents

[apgiorgi]

Part of the Agentic UX spec series. See sibling issues for related buckets.

Current state

Skill installation already exists:

• dci skill claude → installs into ~/.claude/skills/dci-cli/
• dci skill codex, dci skill kiro, dci skill gemini → same pattern per agent
• Embedded payload lives at skills/dci-cli/ in the repo:
  • SKILL.md (entry point)
  • references/ (capabilities, examples, cost-optimization, query-patterns, evals)
  • agents/openai.yaml
• installSkill() in main.go walks the embedded embed.FS and copies it verbatim

What's missing is everything around installation: visibility, hygiene, and ambient context.

Motivation

Agents make better decisions when they know up front what context they're in (which customer, what's recent). Today they have to call dci to find out. axi.md's principle 7 is ambient context: the tool installs itself into the agent's session hooks so state is visible without an explicit call.

Separately, every byte we ship in our skill payload is loaded into every agent session that uses us. Verbosity compounds across thousands of sessions, so it's worth a hygiene pass — see ai-token-economics channel for the "be brief" / squish line of work.

Spec

Skill-management gaps to close

• dci skill list — show embedded skill files with sizes and estimated token counts so users (and CI) can see what they're shipping into agent context
• dci skill update — explicit refresh after a CLI upgrade (today re-running dci skill <agent> would overwrite; make this intent obvious and idempotent, and surface a diff if local edits exist)
• dci skill <agent> --dir <path> override — let users target non-standard config dirs (corp profiles, multi-user setups)
• dci skill --all — install into every detected agent dir on the machine in one shot

Ambient context (new capability)

• dci context (or dci status --agent — name TBD) returns the minimum useful state for an agent to operate: active customer, recent anomaly count, budget alerts, last sync time
• Output is one of the smallest payloads in the CLI — strict ≤500 token budget
• Provide a recommended session hook (Claude Code SessionStart hook, Cursor equivalent, etc.) that runs this and feeds the result into the agent's system context
• Document the hook snippet per agent in README

Skill payload hygiene

• Audit existing files in skills/dci-cli/ for verbosity — apply the "be brief" / squish principle to text we ship
• Add a pre-release script (or CI check) that reports token estimates per skill file and warns on growth
• Consider a budget per file (e.g. SKILL.md ≤ 1k tokens, each references/*.md ≤ 2k)

References

• axi.md — principle 7 (ambient context, self-install into session hooks): https://axi.md/
• Grafana gcx CLI — gcx skills install --all, .agents skill convention: https://grafana.com/blog/get-observability-in-the-terminal-for-you-and-your-agents-with-the-gcx-cli-tool/
• squish-prompts (internal compression tool — applies to skill text too): https://github.com/doitintl/squish-prompts
• claude-mem (persistent memory pattern referenced in ai-token-economics channel): https://github.com/thedotmack/claude-mem
• Caveman vs. "be brief" benchmark: https://www.maxtaylor.me/articles/i-benchmarked-caveman-against-two-words

Open questions

• Naming: dci context vs dci status --agent vs something else (today we already have a status command — does it grow an --agent mode, or is this a new top-level)?
• Does dci skill update need to merge with local edits, or always overwrite (with confirmation)?
• Where do we draw the token-budget line per skill file — gut feel, or based on real session telemetry?
• Should dci skill --all infer targets by scanning for known config dirs, or require explicit listing?

Acceptance criteria

• dci skill list shows embedded files with token estimates
• dci skill update exists with documented overwrite behavior
• --dir override supported on per-agent install commands
• dci context (or equivalent) returns ambient state within a ≤500 token budget
• Recommended session-hook snippet documented in README for at least Claude Code
• Skill token-budget check runs in CI and reports per-file size