139 lines
6.5 KiB
Markdown
139 lines
6.5 KiB
Markdown
# 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](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)
|