Default output: return only the result, blockers, and required evidence. Omit preambles, process narration, repeated context, confidence scores, and follow-up offers. Use at most five bullets unless a required artifact or schema needs more.
Using Agent SkillsOverview
This is the meta-skill for discovering and invoking the right skill, command, or agent for any task. It includes a decision tree for task-to-skill mapping and core operating behaviors that all agents should follow.
When to Use
- Starting a new session and unsure which skill applies
- Task doesn't clearly match a single skill
- Need to understand the full capability landscape
- Debugging why an agent isn't following expected workflows
Decision Tree: Task to Skill Mapping
What are you trying to do?
DEFINE (understand the problem) → Writing requirements before coding? → spec-driven-development
PLAN (break down the work) → Decomposing a spec into implementable tasks? → planning-and-task-breakdown → Researching before planning? → comprehensive-research → Stress-testing a plan or design before committing? → grill-me → Grilling a plan and persisting the decisions as a document? → grill-with-docs
LEARN (teach and grow) → Interactive lessons over multiple sessions with a file-backed workspace? → teach → Week-by-week roadmap and milestones without lesson artifacts? → create-learning-path → Team knowledge base or domain map (not personal tutoring)? → knowledge-architecture
BUILD (write the code) → Implementing a feature across multiple files? → incremental-implementation → Writing tests first? → test-driven-development → Need the right documentation? → source-driven-development
VERIFY (prove it works) → Testing in the browser? → browser-testing-with-devtools → Something is broken? → debugging-and-error-recovery
REVIEW (improve code health) → Reviewing code before merge? → code-review-and-quality → Full repo health check or improvement plan? → repo-audit (or /ai-eng/repo-audit) → Code works but is hard to read? → code-simplification → Security concerns? → security-and-hardening
SHIP (deploy safely) → Preparing for production? → shipping-and-launch → Setting up CI/CD? → ci-cd-and-automation
SPECIALIZED → Building knowledge graphs? → graph-rag → Creating plugins/commands/skills? → plugin-dev → Building a harness workflow runner (Cursor, Claude, OpenCode, OpenAI, Pi)? → agents-sdk-dev (unified — specify harness) → See agents/research-runner/ for reference implementations → Gemini workflow adapter (not shipped yet)? → gemini-agent-sdk → Large cloud multi-agent tree (/orchestrate)? → orchestrate (planned; use agents-sdk-dev with harness=cursor until scripts/cli.ts exists) → Optimizing prompts? → prompt-refinement → Cleaning up AI verbosity? → text-cleanup → Managing git worktrees? → git-worktree → Deploying to Coolify? → coolify-deploy
## Core Operating Behaviors
### 1. Surface Assumptions
Before acting, state what you're assuming:
- "I'm assuming this is a new feature, not a bug fix"
- "I'm assuming we're using the existing auth pattern"
- "I'm assuming the database schema doesn't need changes"
### 2. Manage Confusion
When uncertain, say so explicitly:
- "I'm not sure which pattern applies here"
- "This could be interpreted two ways"
- "I need more context about the expected behavior"
### 3. Push Back
Challenge requirements when needed:
- "This approach will create tight coupling. Consider..."
- "The spec says X, but the existing code does Y. Which is correct?"
- "This change is too large for one commit. Should we split it?"
### 4. Enforce Simplicity
Prefer simple solutions:
- "Can we solve this with a function instead of a class?"
- "Do we need a new dependency, or can we use what we have?"
- "Is there a simpler way to handle this edge case?"
### 5. Scope Discipline
Stay within boundaries:
- "This is out of scope for the current task"
- "I'll note this as a follow-up, not implement it now"
- "The spec covers A and B, but not C. Should I expand scope?"
### 6. Verify
Always prove correctness:
- "Seems right" is never sufficient
- Run tests, check build output, verify runtime behavior
- Provide evidence: passing tests, screenshots, logs
## Anti-Rationalization Table
| Excuse | Counter |
|--------|---------|
| "I'll add tests later" | Tests are proof. Without them, you have no evidence it works. Write tests first or alongside. |
| "This is simple enough to skip the spec" | Simple now, complex later. A 5-minute spec prevents 5-hour rewrites. |
| "I know this pattern, no need to check docs" | Frameworks change. Source-driven development prevents subtle bugs from outdated knowledge. |
| "The code works, no need to simplify" | Working code that's hard to read is technical debt. Future you (or teammates) will pay the cost. |
| "I'll fix the security issue in the next PR" | Security issues are stop-the-line. Fix now or create a tracked issue with severity. |
| "This only affects one file, no review needed" | Every change deserves review. Even small changes can have cascading effects. |
| "I'll document it later" | Undocumented code is a time bomb. Document the why, not the what, while it's fresh. |
## Composition Rules
1. **Agents do NOT invoke other agents** — enforced by platform constraint
2. **Agents MAY invoke skills** — skills are instructions, not agents
3. **The user or a slash command is the orchestrator** — no router agents
4. **Skills auto-activate based on context** — no manual skill selection needed
5. **Teams cannot nest** — flat hierarchy only
## References
- `references/orchestration-patterns.md` — Endorsed and anti-pattern orchestration approaches
- `references/testing-patterns.md` — Test structure, naming, mocking, examples
- `references/security-checklist.md` — Pre-commit checks, OWASP Top 10, secrets management
- `references/performance-checklist.md` — Core Web Vitals, frontend/backend checklists
- `references/accessibility-checklist.md` — Keyboard nav, screen readers, WCAG 2.1 AA