agent-pack-designer

Agent Pack Designer

Turn project context into a small, usable agent pack with explicit evidence.

Installed Version

At the start of a task, read VERSION in this skill directory to identify the installed package version. Include that version in validation reports, audits, release-readiness assessments, and compatibility diagnosis when it helps trace the result. Do not add it to ordinary user-facing replies unless it is relevant.

Default Output Shape

Use the smallest pack that can route work and validate claims:

• AGENTS.md for Codex project rules.
• CLAUDE.md only when Claude Code is an explicit target runtime.
• agents/context_router.md to choose the minimum useful context.
• agents/<primary_workflow_agent>.md for the main project workflow.
• agents/<risk_or_domain_reviewer>.md only when a concrete recurring risk or domain review workflow justifies it.
• agents/validation_reviewer.md to judge evidence level; agents/test_validation.md is an acceptable project-specific alias.
• agents/task_spec_short.md for non-trivial tasks.

Use assets/starter-pack/ as the base structure, then rename placeholder agents to project-specific names.

Pack Categories

Classify files before adding them:

• Core: AGENTS.md, agents/context_router.md, one primary agent, validation reviewer, and agents/task_spec_short.md.
• Conditional reviewer: add one risk or domain reviewer only when current project evidence shows a recurring risk or review workflow.
• Claude-specific: CLAUDE.md and .claude/agents/ only when Claude Code compatibility is required.
• Trigger-only domain agents: add when a mature project has recurring tasks that need distinct context, such as data quality, feature engineering, CV, model training, API runtime, documentation handoff, or submission building.
• Additional trigger-only risk reviewers: add only when a concrete risk deserves a separate review lens, such as leakage, security, reproducibility, metrics, red-team, or public release.
• Optional/future agents: omit from the default pack unless the project already has an active workflow for that area.

Many agents are acceptable for mature projects only when context_router.md keeps the default context to one primary agent plus zero or one triggered reviewer.

Workflow

1. Identify the target project, intended users, source-of-truth files, common tasks, risky contracts, and available validation commands.
2. Read only the references needed for the current job:
   • references/design-workflow.md when generating or restructuring a pack.
   • references/agent-quality-rubric.md when reviewing agent quality.
   • references/validation-levels.md before assigning L0-L5 or release readiness.
3. Build a deliverable coverage inventory from source-of-truth files. Include required, submission, optional, bonus, extra-credit, stretch, artifact, table, and checklist sections. Every deliverable must be represented in the primary workflow, reviewer checklist, or explicit non-goal/status.
4. Choose the smallest useful pack. Include one primary agent and validation reviewer; add a risk or domain reviewer only when it has a distinct trigger, inputs, checklist, output, stop rule, and routing entry.
5. Fill the starter templates with project-specific names, files, commands, forbidden changes, and acceptance criteria.
6. Select the validation profile before running static checks:
   • generated-pack for a materialized project pack;
   • mature-existing-pack for an established project with equivalent role names or layouts;
   • skill-designer-repository for a repository that owns templates and validation tooling. Use scripts/validate_skill.py <path-to-skill> for the installable scaffold and scripts/validate_pack.py --profile <profile> <path> for the selected target.
7. Report the achieved validation level and separate:
   • documented assumptions;
   • evidence visible in files;
   • commands actually run;
   • checks not performed.

Generation Rules

• Prefer one primary implementation agent plus a reviewer only when a concrete recurring risk or domain workflow justifies it. Do not add agents for hypothetical future tasks.
• Optional/future agents are not the same as optional, bonus, extra-credit, stretch, or additional project deliverables. Do not silently omit optional deliverables from the project workflow; include explicit status such as implemented, not implemented, not claimed, or blocked.
• For mature projects, allow multiple trigger-only domain agents when a router prevents loading them all by default.
• Keep implementation, review, validation, and red-team responsibilities separate.
• Keep agents project-specific. Avoid generic agents that could apply to every repository.
• Put rare or speculative roles outside the default pack or omit them.
• Use concise, imperative instructions. Make triggers and stop rules explicit.
• Treat README and specs as intent, not proof. Runtime claims require command output.

Validation Profiles

• Keep unresolved-template checks strict for active files in generated-pack.
• Accept functional aliases under agents/ and .claude/agents/ in mature-existing-pack.
• Treat placeholders under assets/starter-pack/ as intentional in skill-designer-repository.
• Return NOT_APPLICABLE for an explicit profile mismatch instead of converting it into a quality FAIL.
• Do not scan generated reports as active agent-pack inputs.
• Use the installed trusted validator for designer checks; never import or execute a target repository's validator code.

References

Read only the files required by the request. Do not load all references by default.

Stop Rules

• Do not create many agents by default.
• Do not merge implementation, review, validation, and red-team into one agent.
• Do not claim tests or runtime checks passed unless command output was inspected.
• Do not claim public/release readiness below the evidence threshold described in references/validation-levels.md.
• Do not treat validate_pack.py success as L3, L4, or L5; it proves generated-pack consistency only.
• Do not add duplicate role files only to satisfy the wrong validation profile.