agent-skill-authoring

name	agent-skill-authoring
description	Use when adding or modifying rules, finding classes, or agent definitions in the F Prime multi-agent review system. Ensures changes are concise, consistent, and correctly wired across all files.

Skill: Authoring concise agent and skill updates

Guidelines for adding or modifying rules, agents, and skills in the F Prime multi-agent review system. The goal is minimal, consistent changes that AI reviewers can interpret without verbose explanation.

---

0. Where skills and agents live

Skills follow the Agent Skills specification: one directory per skill, holding a file named exactly SKILL.md.

Artifact	Path
Skill	.github/skills/<skill-name>/SKILL.md
Agent	.github/agents/<agent-name>.agent.md
Shared review contract / registry	.github/agents/_shared/

The directory name must equal the name in the skill's frontmatter, using lowercase letters, digits, and hyphens only — a mismatch makes the skill fail to load silently. Frontmatter must carry name and a description that states when to use the skill; optional fields such as argument-hint and triggers are permitted. Any supporting file the skill needs (scripts, templates) goes beside its SKILL.md.

This layout is what Copilot, VS Code, Claude Code, and Devin all scan, so a skill added here is model-invocable in every tool without extra wiring. Cite a skill by its full path (.github/skills/pr-diff-scoping/SKILL.md) where the reader is being sent to it as a source of truth, and by bare name (pr-diff-scoping) in prose, tables, and diagrams where the pointer is incidental.

---

1. Writing rules (fprime-cpp-design and similar)

Be terse. The rule title carries most of the meaning. AI agents are capable of inferring rationale from a well-named rule. Aim for 2-6 lines of prose per rule — comparable to CPP-6 or CPP-15, not CPP-1 or CPP-25 (which are longer because they have genuinely complex scoping).

Checklist for a new rule:

• Title (#### CPP-N — <imperative phrase>): self-explanatory in isolation. A reader should understand the rule from the title alone.
• Body: 2-6 lines. State what is required or forbidden, one exception if any, and a cross-reference to a related rule if relevant. Omit motivation the title already conveys.
• Code examples: include only when the correct pattern is non-obvious. One "avoid / prefer" pair, max 6 lines each. Skip examples when the rule is self-evident from the title (e.g., "use nullptr", "mark overrides with override").
• Finding-class row (§2 table): one row, stable string name. Use the cpp-<description> naming convention.
• Triage hint (§3): one sub-bullet under the appropriate cluster. State default tag and upgrade/downgrade condition.

Anti-patterns to avoid:

• Restating the title in the body ("This rule requires X" when the title already says "Require X").
• Multi-paragraph rationale — put rationale in the PR description, not the rule text.
• Multiple code examples showing the same point.

2. Updating agent files (e.g., fprime-code-review.agent.md)

Agent files reference the skill as the source of truth. When adding a rule to a skill, update the agent file with minimal additions:

• Scope range: bump "CPP-1 through CPP-N" to the new max.
• Finding-class list: add one line for the new finding class.
• Heuristics: append a short clause ("; (CPP-N)") to the relevant scan-order item. Do not duplicate the rule body.
• Triage rules of thumb: append a short clause to the relevant cluster bullet. Mirror the skill's §3 hint verbatim or shorter.

Do not re-explain the rule in the agent file. The skill is the source of truth; the agent file is a lookup index.

3. Updating the registry (agent-registry.yml)

Bump the scope range in scope_summary (e.g., "CPP-33" → "CPP-34"). No other changes needed for a new rule — the registry describes agent scope, not individual rules.

4. Prefer linking existing documentation

Before writing detailed procedural content in a skill, search the repo for existing docs (docs/, README files, how-to guides) that already cover the topic. Skills should provide:

• When / why to use a technique (decision criteria, trade-offs).
• Brief orientation of core constructs (a few bullet points).
• A link to the canonical doc for the full procedure and examples.

Do not reproduce scaffolding steps, file layouts, code templates, or implementation walkthroughs that already exist in a doc. Duplicated content drifts out of sync with the source and risks hallucination when the skill is used as training context.

A good pattern:

Scaffold with `fprime-util new --rule-based-test`. For file layout,
implementation patterns, and full examples see the
[rules-based testing guide](https://github.com/nasa/fprime/blob/devel/docs/how-to/rule-based-testing.md).

A bad pattern: copy-pasting the entire guide into the skill.

When no existing doc covers the topic, the skill is the primary source — write the detail there. But flag it for future extraction into a standalone doc if the content grows beyond ~40 lines of procedural steps.

5. Cross-file consistency checklist

Before committing a new rule, verify all references are updated:

Location	What to update
fprime-cpp-design §1	Rule text
fprime-cpp-design §2	Finding-class row
fprime-cpp-design §3	Triage hint + cluster header
fprime-code-review.agent.md scope	"CPP-1 through CPP-N" (2 occurrences)
fprime-code-review.agent.md finding classes	New entry
fprime-code-review.agent.md heuristics	Clause in scan item
fprime-code-review.agent.md triage	Clause in cluster bullet
agent-registry.yml	scope_summary range