---
name: apex-agent-authoring
user-invocable: true
disable-model-invocation: false
argument-hint: "agent or prompt path and authoring scope"
description: '**WORKFLOW SKILL** — Creates, restructures, and audits GitHub Copilot `.agent.md` and `.prompt.md` files with correct frontmatter, handoffs, model policy, context budgets, and validation. WHEN: "create agent", "author custom agent", "edit agent definition", "agent architecture", "reduce agent tokens", "agent prompt audit". DO NOT USE FOR: routine edits covered by auto-loaded instructions.'
license: MIT
metadata:
  author: jonathan-vella
  version: "1.0"
  category: agent-development
---

# Agent Authoring

Create and restructure Copilot agents without loading extended authoring guidance
into every ordinary agent turn. The thin enforcement layer remains in
[`agent-authoring.instructions.md`](../../instructions/agent-authoring.instructions.md).

## When To Use This Skill

- Create a new `.agent.md` or `.prompt.md`.
- Restructure an oversized or duplicated agent definition.
- Design handoffs or subagent boundaries.
- Select or upgrade an agent model.
- Audit fixed context cost, tool scope, or prompting structure.
- Investigate an agent validation failure requiring more than a local fix.

Do not load this skill for a routine edit where the thin instruction already
states the applicable rule.

## Prerequisites

- Read the target file and its nearest analogous agent once.
- Check `.github/skills/apex-workflow-engine/templates/workflow-graph.json` before
  changing workflow topology.
- Check `.github/model-catalog.json` before changing model labels.
- Preserve user changes and existing runtime contracts.
- Validate every model fallback; preserve exact catalog labels and unknown metadata.
- Distinguish Local prompt adapters from shared Host-compatible skills; neither
  static validation nor a catalog entry proves native model eligibility.

## Workflow

### 1. Classify The Change

Choose the smallest applicable path:

| Change | Load |
| --- | --- |
| Frontmatter field or handoff correction | [Agent file structure](references/agent-file-structure.md) |
| New agent or major body restructure | [Authoring workflow](references/authoring-workflow.md) |
| Model assignment or effort policy | [Model policy](references/model-policy.md) |
| Tool-heavy runtime or fallback behavior | [Runtime guardrails](references/runtime-guardrails.md) |
| Decision capture behavior | [Decision logging](references/decision-logging.md) |
| Vendor-specific prompt audit | Ask the user to invoke `/apex-vendor-prompting`; do not load it automatically |

Load only the references needed for the selected path.
The vendor audit skill is manual-only. Its thin instructions and required validators still apply during authoring;
do not read the skill body as a workaround for its invocation flag.

### 2. Establish Ownership

Keep each concern in one place:

- Agent body: role, goal, workflow-specific constraints, output, stop rules.
- Sol/Terra/Luna main bodies use concise Markdown as an APEX convention, not a
  model-specific vendor claim. Claude (Opus/Sonnet 5.5) main bodies use the Claude
  contract: H1, `## Role`, `<scope_fencing>`, `<output_contract>`, `<stop_conditions>`.
  Leaf workers use bounded role contracts instead of
  mandatory personality or main-agent sections. Preserve content when removing XML.
- Instruction: enforceable rules that apply automatically by file type.
- Skill: on-demand domain workflow and decision guidance.
- Reference: detailed examples, rationale, matrices, and troubleshooting.
- Registry or graph: machine-readable inventory and topology.

Do not copy canonical tables or templates into an agent body.

### 3. Budget Context

- Apply the limits and hand-off framework in
  [`context-optimization.instructions.md`](../../instructions/context-optimization.instructions.md).
- Keep tool lists minimal and handoffs intentional.
- Move long templates to references or templates.
- Prefer one compact structured example.
- Remove prose already supplied by an auto-loaded instruction.
- Estimate fixed cost using body bytes, matched instruction bytes, tool schemas,
  and mandatory skill reads.

Use the `apex-context-management` skill for runtime compression or debug-log audits.

### 4. Implement Incrementally

1. Update frontmatter and the smallest body section first.
2. Run the focused agent validator.
3. Move optional detail into references only after behavior remains valid.
4. Update model registry or workflow graph mirrors when their canonical source
   changes.
5. Update documentation when an agent or skill is added, renamed, or removed.

### 5. Validate

Run focused fixture tests first; they do not stage files into the active agent tree:

```bash
node --test tools/tests/lib/parse-frontmatter.test.mjs tools/tests/validate-agents/classify-model.test.mjs tools/tests/vendor-prompting/run.test.mjs
```

After concurrent agent edits settle, integration checks are:

```bash
npm run validate:agents
npm run lint:vendor-prompting
npm run validate:model-consistency
npm run validate:skills
npm run lint:md
```

For model changes also run `npm run validate:model-catalog` and
`npm run validate:deprecated-models`.

## Output Expectations

Return:

- Files changed and ownership rationale
- Fixed-context reduction when slimming an agent
- Preserved runtime contracts and anchors
- Validation commands and results
- Any documentation or generated inventory updated

## Troubleshooting

| Symptom | Action |
| --- | --- |
| Agent is not discovered | Validate frontmatter, filename, description form, and model syntax |
| Handoff fails validation | Verify target name, allowed fields, and input/output enrichment |
| Skill is reported orphaned | Reference `.github/skills/apex-agent-authoring/SKILL.md` canonically |
| Model consistency fails | Treat agent frontmatter as canonical, then update registry mirrors |
| Context remains large | Remove duplicated instruction prose and move phase-specific detail to references |

## Reference Index

- [Agent fleet assessment](references/assess-agents.md): definition scorecards and a gated remediation plan.
- [.github assessment](references/assess-github-folder.md): static authoring-asset inventory and review.
- [Assessment design history](references/plan-four-layer-agent-assessment.md): reference-only, not executable.

Assessments never edit authoring assets in the review pass. Optional supplied log profiles
inform scorecards; log capture, context audit, and runtime compression remain owned by
[`apex-context-management`](../apex-context-management/SKILL.md).

- [Agent file structure](references/agent-file-structure.md)
- [Authoring workflow](references/authoring-workflow.md)
- [Model policy](references/model-policy.md)
- [Runtime guardrails](references/runtime-guardrails.md)
- [Decision logging](references/decision-logging.md)
- [Skill authoring](references/skill-authoring.md): locations, layout, loading and `context` policy detail.