Agent Authoring

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.

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/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.

Workflow

1. Classify The Change

Choose the smallest applicable path:

Load only the references needed for the selected path.

2. Establish Ownership

Keep each concern in one place:

• Agent body: role, goal, workflow-specific constraints, output, stop rules.
• 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.
• 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 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:

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

Reference Index

• Agent file structure
• Authoring workflow
• Model policy
• Runtime guardrails
• Decision logging