How to use agents in Worklayer

Use Case: When you need a role-based AI assistant for exploratory work like release planning or user research analysis Time to Complete: 3 minutes to invoke, varies by task Prerequisites: Workspace set up, agents created (or use built-in agents)

Quick Answer

In Worklayer, agents are role-based AI assistants (like "Release Planner" or "User Research Analyst") that you invoke with @agent-name in chat. Unlike skills (which run specific workflows), agents are conversational and adaptive, asking clarifying questions and helping you think through complex problems.

Step-by-Step Instructions

Step 1: Understand Agents vs Skills

Agent: Role-based AI helper that's conversational and adaptive

Example: @release-planner, @user-research-analyst
Use for: Exploratory work, strategic thinking, complex decision-making

Skill: Repeatable command that runs a specific workflow

Example: /bug-prioritizer, /generate-prd
Use for: Repeatable tasks with clear steps

Step 2: Invoke an Agent

Reference an agent using @agent-name in your chat prompt.

Example:

@release-planner - I want to ship an alpha release next week. What should be in scope?

Step 3: Respond to Agent Questions

Agents ask clarifying questions before providing recommendations.

Example agent response:

Before I suggest scope, I have a few questions:

1. What's your primary goal for this alpha release?
2. How many alpha testers are you targeting?
3. Are there any must-have features for alpha validation?

Step 4: Review Agent Recommendations

After you answer, the agent provides recommendations grounded in your context files and data.

Step 5: Iterate or Act

Continue the conversation to refine recommendations, or act on the agent's output.

Example: End-to-End Workflow

Let's use a Release Planner agent to plan an alpha release.

Step 1: Invoke agent:

@release-planner - I want to ship an alpha release by March 30. Help me define scope and identify risks.

Step 2: Agent asks clarifying questions:

Great! Before I suggest scope, I need to understand:

1. Primary goal: Is this for user validation, feedback collection, or proving technical feasibility?
2. Alpha tester count: How many testers are you targeting? (10? 50? 100?)
3. Must-have features: Are there specific features that must work for alpha to be useful?
4. Known blockers: Are there any P1 bugs or dependencies we need to resolve first?

Step 3: You respond:

1. Goal: User validation - prove that PMs will use Worklayer for real work
2. Tester count: 10 alpha testers from waitlist
3. Must-have features: Context + Templates + AI chat. MCP integrations are nice-to-have but not required.
4. Blockers: Visual mode crashes with large Mermaid diagrams (P1)

Step 4: Agent provides recommendations:

## Alpha Release Scope (March 30, 2026)

### In Scope
- Core workflow: Context → Templates → Outcomes (must work reliably)
- AI chat with file references (@Context/Product/...)
- Task planner (basic functionality: create, update, complete)
- Visual mode for markdown (must fix Mermaid crash bug first - see WL-101)

### Out of Scope (Post-Alpha)
- MCP integrations (Jira, Slack) - nice-to-have, not critical for validation
- Skills and Agents builder - power user feature, not needed for alpha
- Excel/PDF support - can wait until beta

### Risks
1. **P1 blocker**: Visual mode crashes with large Mermaid diagrams (WL-101). This must be fixed before alpha.
2. **Onboarding friction**: Alpha testers need hand-holding. Plan for manual onboarding calls.
3. **Context file creation**: Users may struggle to populate Context files. Provide examples or templates.

### Next Steps
1. Fix WL-101 (visual mode crash) - target: March 25
2. Test core workflow with 2-3 internal users - target: March 27
3. Send alpha invites to 10 waitlist users - target: March 28

Step 5: Act on recommendations or continue conversation:

This looks good. Can you pull open P1 bugs from Jira and confirm WL-101 is the only blocker?

Agent pulls Jira data and confirms.

Time: 10 minutes of conversation → clear release plan

Tips & Best Practices

Use agents for exploration: When you're unsure about scope, priorities, or approach, invoke an agent to help you think through options.
Let agents ask questions: Don't try to provide all context upfront. Agents will ask clarifying questions to gather what they need.
Reference context files: Agents can access your Context files automatically. The more context you have stored, the better their recommendations.
Iterate: Agents are conversational. If the first recommendation doesn't fit, ask follow-up questions to refine.
Combine with skills: After an agent helps you plan, use a skill to execute. Example: Agent plans release → Skill pulls Jira data and updates priorities.

Common Mistakes to Avoid

Using agents for repeatable tasks: If you're running the same workflow every week (like bug prioritization), create a skill instead. Agents are for exploratory, one-time thinking.
Not responding to questions: If an agent asks clarifying questions and you ignore them, it will generate generic recommendations. Always answer agent questions.
Expecting agents to execute: Agents provide recommendations and analysis. They don't automatically update Jira or create files (skills do that). Use agents for thinking, skills for doing.