Creating Agents And Skills

Skill: creating-agents-and-skills

The governance gate for extending this kit. Goal: people add capabilities only when they help, build them with quality, and every installed tool folder stays in sync.

Follow three phases in order: Decide → Author → Propagate.

---

Phase 1 — Decide what (if anything) to build

Run these gates before creating anything. If a gate says stop, explain why and stop.

• LLM-native? → don't create. If a capable model already does this well ("write clean

code", "use CTEs", "explain this function"), no artifact is needed. Just do the task.

• Narrow knowledge / a tool / a format / a checklist? → make a SKILL. Most additions are

skills: a team naming standard, a framework's rules, a validation procedure. Skills auto-activate by description and cost almost nothing until used.

• A distinct role with its own domain and judgement? → make an AGENT. Only when there's a

persona that owns a body of work (like data-engineer). Agents are expensive (routing, attention); the bar is high.

• Overlaps an existing agent/skill? → extend it, don't add a near-duplicate. Ambiguous

routing between two similar artifacts degrades results.

• A repeatable multi-step procedure the user invokes? → make a WORKFLOW (slash command).

> Default to a skill. Recommend an agent only if you can name the distinct domain it owns and > confirm nothing existing covers it.

---

Phase 2 — Author it lean

Write only domain/org-specific signal. No filler, no restating what the model knows. English.

Agent — .agent/agents/.md:

---
name: 
description: One sharp sentence on what it does + trigger keywords (drives routing).
tools: Read, Grep, Glob, Bash, Edit, Write
model: inherit
skills: skill-a, skill-b        # optional hints; skills also self-activate
---
# 
 → domain rules → handoffs to other agents → out-of-scope.

Skill — .agent/skills//SKILL.md (gerund-style name, e.g. validating-dbt-models):

---
name: 
description: What it does AND when to use it, in the third person, with trigger words so it
  auto-activates (e.g. "Use when the user asks to ... "). This is the most important field.
---
# Skill: 
 → concrete rules or steps. Keep the body under ~500 lines; move long reference
material to sibling files (e.g. reference.md, scripts/) and link them.

Write descriptions in the third person ("Generates...", "Use when...") — never "I can help". The description is what makes the skill fire without the user naming it.

Workflow — .agent/workflows/.md: description frontmatter + concise numbered steps.

---

Phase 3 — Propagate to every installed tool folder

A capability must exist, identically, in each AI tool the project uses — each in its native format. Pick the path that matches the project:

Path A — Source of truth present (.agent/ + scripts/sync_agents.py exist)

This is the kit repo or an Antigravity install. Author in .agent/ only, then sync:

python scripts/sync_agents.py

The script regenerates .claude/, .github/, .opencode/, .cursor/, and root AGENTS.md (which also covers OpenAI Codex). Never hand-edit those — they're overwritten. Done.

Path B — No source of truth (user installed one or more tool flavors)

Detect which folders exist and write the artifact into each present folder in its native format (the body content stays identical; only frontmatter changes). Format mapping:

| Concept | .agent (Antigravity) | .claude (Claude Code) | .github (Copilot) | .opencode (OpenCode) | .cursor (Cursor) | |---|---|---|---|---|---| | Agent | agents/.md | agents/.md (identical) | agents/.agent.md — frontmatter name, description only (no tools) | agents/.md — frontmatter description, mode: subagent, permission (drop tools/model/name/skills) | — (Cursor has no file-based agents) | | Skill | skills//SKILL.md | skills//SKILL.md (identical) | skills//SKILL.md (identical) | skills//SKILL.md (identical) | — (no skills concept) | | Workflow | workflows/.md | commands/.md (native slash command) + workflows/.md | prompts/.prompt.md — frontmatter name, description; body starts **Context:** ${selection} | commands/.md (identical) | commands/.md (identical) | | Global rule | rules/rules.md (with trigger: always_on) | CLAUDE.md (rules + commands section) | copilot-instructions.md (rules) | root AGENTS.md (rules) | rules/.mdc — frontmatter description, globs, alwaysApply: true |

Rules:

• Strip the trigger: always_on frontmatter from rules.md when writing it anywhere

outside .agent/ — it's Antigravity-only and is noise everywhere else.

• OpenCode reads the root AGENTS.md, not .opencode/AGENTS.md — don't create the latter.

The same root AGENTS.md is what OpenAI Codex reads, so Codex needs no dedicated folder.

• Frontmatter differs per tool (Copilot agent/prompt, OpenCode agent, Cursor rule/mdc); the

body is a verbatim copy everywhere.

• Create the same `` in all present folders — do not leave a tool behind.
• If the user installed only one folder but wants multi-tool support, offer to add the others.

Verify parity

After either path, confirm the artifact exists in every present tool folder and that no folder references something that no longer exists. State which folders you wrote.

---

Anti-patterns

• Creating an agent for a single tool or task (e.g. "GitAgent"). Tools don't need agents.
• Putting episodic guidance in the always-on rules — it belongs in a skill like this one.
• Editing generated folders (.claude/.github/.opencode/.cursor/AGENTS.md) when .agent/ exists.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: luccapinto
• Source: luccapinto/agentic-data-kit
• License: MIT

Install and usage instructions live in the source repository linked above.