Agent Skills: Using Agent Skills

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 Skills

Overview

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