Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
AI & knowledge

agent-customization

LLM-powered injection of project context into installed agent templates via `aspens customize agents`

aspenkit · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add aspenkit/aspens --skill agent-customization

About this skill


name: agent-customization description: LLM-powered injection of project context into installed agent templates via aspens customize agents triggers: files: - src/commands/customize.js - src/prompts/customize-agents.md keywords: - customize - agents - subagent - agent customization

You are working on agent customization — the feature that reads a project's skills and CLAUDE.md, then uses Claude CLI to inject project-specific context into generic agent files in .claude/agents/.

Domain purpose

aspens customize agents makes generic, bundled agent templates project-aware. It pulls the repo's skills + CLAUDE.md as ground truth and asks Claude to add a tech-stack line, 3-5 project conventions, and real commands into each agent — without touching the agent's core logic.

Business rules / invariants

  • Claude-only feature. Throws CliError for Codex-only repos (config.targets === ['codex']). Codex CLI has no agent concept.
  • Base skill is required. Pre-flight throws CliError("Run 'aspens doc init' first — base skill is required for agent context.") if .claude/skills/base/skill.md is missing.
  • Skills (.claude/skills/**) are the single source of truth for project context. The prompt must not invent other context directories.
  • Read-only tools only. Claude is invoked with allowedTools: ['Read', 'Glob', 'Grep'] — no edits/writes from the LLM itself.
  • Output paths restricted to .claude/. parseFileOutput() rejects anything else; writeSkillFiles(..., { force: true }) does the actual write.

Non-obvious behaviors

  • Frontmatter preservation is split across LLM + code. The prompt instructs Claude to preserve YAML frontmatter verbatim (including NOT adding a skills: line). Then maybeInjectBaseSkill() post-processes each returned file to add skills: [base] into the frontmatter — this keeps agents valid even when installed via aspens add agent without a prior doc init.
  • --reset semantics: without --reset, agents that already declare skills: are left alone; with --reset, any existing skills: line is overwritten to skills: [base]. Used to roll out v0.8 upgrades to previously-customized agents.
  • ## Project context block is verbatim-preserved by the prompt — it carries conditional read instructions for code-map / domain skills.
  • CLAUDE.md is truncated at 3000 chars in gatherProjectContext(); skills are passed in full.
  • Agent discovery: findAgents() recursively walks .claude/agents/, extracts name: via regex, falls back to filename if missing.
  • Default timeout 300s via resolveTimeout(options.timeout, 300); ASPENS_TIMEOUT env var honored with warning on invalid value.

Critical files (purpose, not inventory)

  • src/commands/customize.js — orchestrator: preflight, agent discovery, context gathering, per-agent Claude calls, post-LLM skills: [base] injection, write.
  • src/prompts/customize-agents.md — system prompt; enforces frontmatter + ## Project context preservation and bans file-inventory / hub-ranking output.

Critical Rules

  • Never let the LLM emit a skills: line — the prompt forbids it and the code adds it. If you change one, change both.
  • Never weaken path sanitization — only .claude/ paths may be written.
  • Never duplicate file-inventory or hub-ranking output in customized agents — the graph hook supplies that dynamically.
  • Do not bypass the base-skill preflight — agents without base context regress to generic behavior.

Last Updated: 2026-05-11