ai-docs/Agents.md

Agents

Purpose

This file defines how to use agent-style workflows and skills in this project, so tasks are clear, scoped, and repeatable. It is internal guidance for the assistant, not reader-facing documentation.

What Are Agents vs Skills?

Short answer:

• Skills = reusable tools or playbooks the AI can call when needed. Like a toolbox for a generalist.
• Custom agents (your /assets/agents/ folders) = specialized AI teammates with their own personality, expertise, and decision-making style. Like building a team of experts.

You can get pretty far with just the default agent (the generalist one) + skills, but custom agents unlock a completely different level: turning one smart generalist into a full specialized team.

Why people actually create and use custom agents

Here’s what changes in practice:

True specialization & expertise

• A default agent + “use the React skill” still thinks like a generalist.
• A custom @react-architect agent has deep, baked-in knowledge (your exact component patterns, state management preferences, accessibility rules, performance gotchas). It doesn’t forget or need reminding.

Different thinking styles / risk levels

• @rapid-prototype agent → fast, experimental, okay with temporary hacks
• @production-safety agent → extremely conservative, asks for confirmation on big changes, always checks security/performance first
• @security-auditor agent → thinks about threats, OWASP, secrets scanning before writing a single line You can’t get this reliably just by prompting the default agent every time.

Multi-agent orchestration (the real 2026 power move) Tools like Windsurf Cascade, Claude Code Subagents, VS Code Agents, RooCode, Cline, and even Cursor (via agent handoffs) let agents delegate to each other: Planner Agent → Backend Agent → Frontend Agent → Tester Agent → Reviewer Agent This is way smoother and more reliable than one default agent trying to do everything.

Convenient UX You just type @security review this or switch to the agent in the sidebar. No long prompt every session.

Consistency across sessions & team members The custom agent always behaves the same way. No “mood” variation like the default agent sometimes has.

Curated tool/skill usage You can restrict or prioritize certain skills for that agent only (e.g. the security agent only gets vulnerability-scanning skills and is blocked from deploying).

Real-world analogy

Default agent + skills = One extremely capable senior developer with a huge toolbox. You still have to guide them a lot. Custom agents = You built a small specialized team (architect, frontend wizard, security lead, QA expert). You just assign the right person to the task.

Most power users and big teams in 2026 do both:

• A rich library of skills (your /assets/skills/)
• Several custom agents (your /assets/agents/) that know exactly which skills to use and how.

That’s exactly why having separate /agents/ and /skills/ folders in your repo is such a smart setup.

Audience And Tone Rules

Assume the reader is new to AI and needs detailed, step-by-step guidance.

• Read the PRD.md and README.md to understand this project.
• On the first response in a new chat, read this file and summarize the repo purpose in 1-2 sentences before proceeding.
• Be specific and explicit. Avoid shorthand.
• Explain terms in plain language.
• Provide an example whenever possible.
• Format chat or code examples consistently: use "Example prompt:" with a fenced text block for chat prompts, and "Example code:" with the right language for code.
• Prefer checklists, short steps, and concrete outcomes.
• Assume the reader is an expert engineer but a beginner at AI.

Sync Expectation

Keep this file aligned with PRD, README, and docs/planning/AI-Docs-Plan.md when workflows, scope, or structure change.

When to Use Agents

• Multi-step changes across files.
• Refactors with clear acceptance criteria.
• Audits or documentation updates.

Common Agent Use Cases

• Create or expand documentation sections.
• Plan a refactor before making edits.
• Summarize and assess risks across files.

How to Use Agents

1. Define the outcome in one sentence.
2. List inputs (files, context, constraints).
3. Ask for a plan, then approve before edits.
4. Ask for focused changes and verification steps.

Contribution Workflow (Required)

When using AI to add or change docs in this repo:

1. Point the AI to this file and PRD.md first.
2. Ask for a short plan before edits.
3. Require explicit examples and step-by-step language in outputs.
4. Update the index when adding new markdown files.
5. Verify formatting (bullets, code blocks, and links) before commit.

Doc Navigation Pattern (Required)

If you add, remove, or rename any file under docs/ai:

1. Update docs/ai/index.md with the new or removed entry.
2. Add or update the page breadcrumb ("You are here") on the page.
3. Add or update the page "Contents" block.
4. Add or update the "Next Steps" block so readers can navigate forward.
5. Verify all links still resolve.

Example Checklist

• Index updated in docs/ai/index.md
• Breadcrumb updated on the page
• Contents block updated
• Next Steps block updated
• Links verified

When A New Chat Starts

If you had to restart a chat and re-explain the goal, add a short reminder so the assistant places content in the reader-facing docs instead of workflow files.

Also, the first response in a new chat must confirm it read Agents.md and briefly state what this repo is about at a high level.

What To Say (Plain English)

• "Treat this repo like a book for developers. Put reader-facing guidance in docs/ai, not in Agents.md."
• "If placement is unclear, ask where the content should live before editing."

Commit And Push After Repo Updates

If you update any file in this repo, commit and push right away so other developers do not lose their local changes. If you are unsure, ask and confirm before pushing.

Skills Sync

This repo uses a skills manifest to standardize skills across developers.

1. Review the curated list under assets/.
2. Run ./assets/setup.sh skills (or skills ios, skills android).
3. Run ./assets/setup.sh agents to install agents.
4. Run ./assets/setup.sh instructions to install instructions.
5. Or run ./assets/setup.sh all ios to install everything at once.
6. Restart your editor if needed.

Suggested Agent Request Template

• Goal: (one sentence)
• Inputs: (files, context, constraints)
• Output: (expected deliverable)
• Verification: (tests or checks)