Build a Slack Agent Company From One Markdown File
Create a complete operating specification for agent roles, skills, memory, approvals, handoffs, Slack communication, backend implementation, launch testing, and reporting.
Download the Slack Agent Company Tutorial and Template
Build a Slack Agent Company From One Markdown File
Define agent roles, memory, workflows, and the technical build in a single operating specification.
What you will achieve
You will create one agent-company.md file, then use it to configure Slack apps, guide a coding assistant through the backend build, onboard agents, and test real work.
Who this is for
Business owners, operators, and technical builders who want visible AI workflows inside Slack.
Difficulty: Advanced
Short tutorial
Define agent roles, memory, workflows, and the technical build in a single operating specification.
Guide: Build a Slack Agent Company From One Markdown File
Time: 60-90 minutes
What you will build
This tutorial turns Slack into a visible workspace for AI agents. Each agent receives company context, a defined role, skills, feedback memory, and tasks. A public HTTPS backend connects Slack events to your chosen AI provider and sends responses back into Slack.
Your final artifact is one file named agent-company.md. It acts as both the operating manual for your agents and the implementation specification for the person or coding assistant building the integration.
The architecture is:
- A separate Slack app gives each agent an identity.
- Slack events are sent to your public HTTPS backend.
- The backend verifies each request with the Slack signing secret.
- The backend loads the relevant instructions from
agent-company.md. - Your chosen AI provider generates the agent's response or work.
- The backend returns the result to the appropriate Slack channel or thread.
- Feedback and corrections are added to the agent's memory section.
Start with one or two agents. Add more only after they reliably complete real tasks.
Step 1: Create agent-company.md
Create a local project folder, then create a file named `agent-company.md` inside it. Copy the complete template below into that file.
Replace every bracketed placeholder before connecting the system to Slack.
# Agent Company Operating System ## 1. Company context ### Company name [COMPANY NAME] ### What we do [DESCRIBE THE BUSINESS, PRODUCT, OR PERSONAL OPERATING SYSTEM] ### Mission [STATE THE OUTCOME THE COMPANY EXISTS TO CREATE] ### Customers or stakeholders [DESCRIBE WHO RECEIVES THE WORK] ### Current priorities 1. [PRIORITY] 2. [PRIORITY] 3. [PRIORITY] ### Quality standard Work must be accurate, useful, clearly structured, and appropriate for the intended audience. Agents must follow the role boundaries, required workflow, and approval rules in this document. ### Company constraints 1. Do not expose credentials, private client information, or confidential company data. 2. Do not claim that work is complete unless the requested deliverable has been produced. 3. Identify missing information instead of silently inventing it. 4. Escalate decisions that require human judgment or approval. ## 2. Agent roster ### Agent 1 Name: [AGENT NAME] Department: [DEPARTMENT] Slack app name: [SLACK APP NAME] Slack channels: [CHANNELS] Role purpose: [WHY THIS ROLE EXISTS] Responsibilities: 1. [RESPONSIBILITY] 2. [RESPONSIBILITY] 3. [RESPONSIBILITY] Inputs: 1. [BRIEFS, FILES, MESSAGES, OR DATA THIS AGENT RECEIVES] Outputs: 1. [DOCUMENTS, CODE, ANALYSIS, OR UPDATES THIS AGENT PRODUCES] Available skills: 1. [SKILL OR WORKFLOW] 2. [SKILL OR WORKFLOW] Approval rules: 1. [WHAT THE AGENT MAY COMPLETE AUTONOMOUSLY] 2. [WHAT REQUIRES HUMAN APPROVAL] Handoff rules: 1. Send [TYPE OF WORK] to [AGENT OR HUMAN OWNER]. 2. Request review from [AGENT OR HUMAN OWNER] before [ACTION]. ### Agent 2 Name: [AGENT NAME] Department: [DEPARTMENT] Slack app name: [SLACK APP NAME] Slack channels: [CHANNELS] Role purpose: [WHY THIS ROLE EXISTS] Responsibilities: 1. [RESPONSIBILITY] 2. [RESPONSIBILITY] 3. [RESPONSIBILITY] Inputs: 1. [BRIEFS, FILES, MESSAGES, OR DATA THIS AGENT RECEIVES] Outputs: 1. [DOCUMENTS, CODE, ANALYSIS, OR UPDATES THIS AGENT PRODUCES] Available skills: 1. [SKILL OR WORKFLOW] 2. [SKILL OR WORKFLOW] Approval rules: 1. [WHAT THE AGENT MAY COMPLETE AUTONOMOUSLY] 2. [WHAT REQUIRES HUMAN APPROVAL] Handoff rules: 1. Send [TYPE OF WORK] to [AGENT OR HUMAN OWNER]. 2. Request review from [AGENT OR HUMAN OWNER] before [ACTION]. ## 3. Standard task workflow For every assigned task: 1. Read the company context and your role instructions. 2. Restate the requested outcome in one sentence. 3. Check that the required inputs are available. 4. If essential information is missing, ask a specific question in the task thread. 5. Select the relevant skill or documented workflow. 6. Complete the work within your role boundaries. 7. Ask the designated reviewer for feedback when required. 8. Post the final deliverable in the original Slack thread. 9. Report the status as completed, blocked, or awaiting approval. 10. Record reusable feedback in the memory section. ## 4. Slack communication protocol 1. Keep each task inside its original thread. 2. Begin updates with one of these labels: Working, Blocked, Review requested, Awaiting approval, or Completed. 3. When blocked, state what is missing and who can provide it. 4. When handing off work, name the receiving agent and describe the expected output. 5. When completing work, include the deliverable or its location, a concise summary, and any remaining risk. ### Completion message template Status: Completed Task: [TASK NAME] Result: [WHAT WAS PRODUCED] Deliverable: [PASTE THE OUTPUT OR STATE ITS LOCATION] Review: [REVIEW STATUS] Remaining risk: [NONE OR EXPLAIN] ### Blocked message template Status: Blocked Task: [TASK NAME] Blocker: [WHAT PREVENTS COMPLETION] Required input: [EXACT INFORMATION OR ACTION NEEDED] Owner: [PERSON OR AGENT WHO CAN UNBLOCK IT] ## 5. Task specification Use this structure when creating work for an agent. Task title: [SHORT ACTION ORIENTED TITLE] Owner: [AGENT] Slack channel: [CHANNEL] Outcome: [THE FINISHED RESULT] Context: [RELEVANT BACKGROUND] Inputs: [FILES, LINKS, DATA, OR MESSAGES] Required skill: [SKILL OR WORKFLOW] Priority: [LOW, MEDIUM, HIGH, OR URGENT] Due date: [DATE AND TIME] Reviewer: [AGENT OR HUMAN] Approval required: [YES OR NO] Definition of done: 1. [TESTABLE CONDITION] 2. [TESTABLE CONDITION] 3. [TESTABLE CONDITION] ## 6. Skills ### Skill: [SKILL NAME] Purpose: [WHAT THIS SKILL ENABLES] Used by: [AGENTS] Required inputs: 1. [INPUT] Procedure: 1. [ACTION] 2. [ACTION] 3. [ACTION] Output format: [EXACT FORMAT THE AGENT SHOULD RETURN] Quality checks: 1. [CHECK] 2. [CHECK] Escalate when: 1. [CONDITION] ## 7. Agent memory Memory contains durable feedback that should change future behavior. Do not store credentials or unnecessary private data here. ### [AGENT NAME] memory #### Preferences 1. [REUSABLE PREFERENCE] #### Successful patterns 1. [APPROACH THAT PRODUCED A GOOD RESULT] #### Corrections 1. Date: [DATE] Situation: [WHAT HAPPENED] Feedback: [WHAT SHOULD CHANGE] Future behavior: [SPECIFIC RULE TO FOLLOW NEXT TIME] ### [AGENT NAME] memory #### Preferences 1. [REUSABLE PREFERENCE] #### Successful patterns 1. [APPROACH THAT PRODUCED A GOOD RESULT] #### Corrections 1. Date: [DATE] Situation: [WHAT HAPPENED] Feedback: [WHAT SHOULD CHANGE] Future behavior: [SPECIFIC RULE TO FOLLOW NEXT TIME] ## 8. Daily company activity report Report date: [DATE] ### Completed 1. Agent: [NAME] Task: [TASK] Result: [RESULT] ### In progress 1. Agent: [NAME] Task: [TASK] Next action: [ACTION] ### Blocked or failed 1. Agent: [NAME] Task: [TASK] Problem: [PROBLEM] Required correction: [ACTION] ### Human decisions required 1. [DECISION] ### Memory updates 1. Agent: [NAME] New rule: [REUSABLE FEEDBACK] ## 9. Technical implementation specification ### Required components 1. One Slack app for each agent identity. 2. A public HTTPS backend. 3. Slack request verification using each app's signing secret. 4. Event handlers for the Slack interactions used by the agents. 5. A secure connection to the selected AI provider. 6. Logic that maps each Slack app to its role, skills, channels, and memory in this document. 7. Logic that sends responses to the correct Slack channel or thread. 8. Secure environment variables for Slack tokens, Slack signing secrets, and AI provider keys. ### Event flow 1. Slack sends an event to the public HTTPS endpoint. 2. The server verifies the request with the relevant Slack signing secret. 3. The server identifies the agent and conversation. 4. The server loads company context, role instructions, relevant skills, and agent memory. 5. The server sends that context and the task to the selected AI provider. 6. The server sends the result back to the correct Slack channel or thread. 7. Task status and reusable feedback are recorded for later review. ### Environment variable inventory SLACK_AGENT_1_BOT_TOKEN=[SECRET] SLACK_AGENT_1_SIGNING_SECRET=[SECRET] SLACK_AGENT_2_BOT_TOKEN=[SECRET] SLACK_AGENT_2_SIGNING_SECRET=[SECRET] AI_PROVIDER_API_KEY=[SECRET] Never commit real secret values to this document or source control. ## 10. Optional command center The command center may display: 1. Open work. 2. Active conversations. 3. Task owner. 4. Required skill. 5. Priority. 6. Due date. 7. Slack channel. 8. Completed work. 9. Blockers and failures. 10. Daily company activity reports. A task creation form should capture the fields in the task specification section of this document. ## 11. Launch checks 1. Each agent has a distinct Slack app identity. 2. Every role has explicit responsibilities and approval boundaries. 3. At least one skill is documented as a repeatable procedure. 4. Tokens and signing secrets are stored securely. 5. Slack requests are verified before processing. 6. The backend is available through a public HTTPS URL. 7. Each agent can receive a test task and reply in Slack. 8. Replies appear in the intended channel or thread. 9. Human feedback can be converted into a memory correction. 10. A real task has been completed from assignment through review.
Step 2: Define the first agents
The source example uses five roles: a CEO, product lead, software specialist, marketing specialist, and sales specialist. You do not need all five immediately.
Choose roles based on real workflows, not novelty. A strong initial pair might be:
| Agent | Responsibility | Example task |
|---|---|---|
| Marketing agent | Draft and review campaign assets | Turn a client brief into three campaign concepts |
| Software agent | Implement and review code | Build a requested feature and post a test summary |
Give agents human readable names if that helps you distinguish the roles. Their behavior still comes from the role description, skills, and memory in the file.
For each agent, complete these parts of agent-company.md:
- Role purpose.
- Responsibilities.
- Expected inputs and outputs.
- Available skills.
- Approval boundaries.
- Handoff rules.
- Initial memory preferences.
Step 3: Document at least one real skill
A role description explains ownership. A skill explains exactly how work is performed.
Choose a recurring workflow you already understand. You can derive the procedure from an existing process document or from a narrated screen recording of yourself doing the work. Put the resulting steps in the Skills section.
For example:
### Skill: Review a client brief Purpose: Convert an incoming brief into an actionable delivery plan. Used by: Marketing agent Required inputs: 1. Client objective. 2. Intended audience. 3. Deliverables. 4. Deadline. 5. Known constraints. Procedure: 1. Summarize the requested business outcome. 2. Extract every requested deliverable. 3. Identify missing information and contradictions. 4. Propose a sequence of work. 5. Assign an owner and reviewer to each item. 6. Return the plan in the required format. Output format: 1. Objective. 2. Deliverables. 3. Missing information. 4. Work plan. 5. Owners and reviewers. 6. Risks. Quality checks: 1. Every requested deliverable appears in the plan. 2. Unknown information is labeled rather than invented. Escalate when: 1. The deadline conflicts with the requested scope. 2. The brief lacks an objective or required deliverable details.
Step 4: Create the Slack agent identities
Repeat this process for each agent you are launching:
- Open Slack's API app management interface and create a new app.
- Give the app the same identity recorded in
agent-company.md. - Select the intended Slack workspace.
- Configure the app's bot permissions.
- Configure event subscriptions for the interactions your backend will handle.
- Install the app to the workspace.
- Copy its bot user OAuth token and signing secret into secure environment variables.
- Invite the app to the channels where it should work.
The source refers to exact bot token scopes and event subscriptions shown on screen, but those lists are not present in the supplied transcript. Do not guess them. Select only the permissions and events required by your implementation, then confirm them against Slack's current app configuration interface.
Treat every OAuth token and signing secret as a credential. Do not paste real values into agent-company.md.
Step 5: Build the HTTPS backend
The backend can use Node.js, Python, Go, or another server technology you can maintain. It must implement the event flow defined in your Markdown file.
Give the following prompt and your completed agent-company.md to your coding assistant:
Build the Slack agent backend described in the attached agent-company.md file. Work with me interactively. Before writing code, inspect the specification and ask for any missing technical decisions, including the programming language, deployment target, AI provider, Slack events, and required Slack permissions. The implementation must: 1. Expose a public HTTPS compatible Slack event endpoint. 2. Verify incoming Slack requests using the correct signing secret. 3. Support the Slack events selected during configuration. 4. Map each Slack app identity to the correct role in agent-company.md. 5. Load company context, the assigned role, relevant skills, and that agent's memory before requesting an AI response. 6. Preserve the originating Slack channel and thread when sending a response. 7. Read all credentials from environment variables. 8. Never place credentials in source code or agent-company.md. 9. Provide local setup, environment variable, deployment, and test instructions. 10. Explain each required Slack permission and event before asking me to enable it. Do not invent missing credentials, deployment details, scopes, or event names. Ask me to confirm them where needed. Build the smallest testable version for one agent first, then show me how to add the remaining agents.
Review the generated implementation before deploying it. In particular, confirm that request verification happens before an event is processed and that secrets come from environment variables.
Step 6: Connect the AI provider
Create an API key for your selected AI provider and store it securely using the environment variable named in the specification:
AI_PROVIDER_API_KEY
The backend should construct each request from four relevant sections of agent-company.md:
- Company context.
- The active agent's role.
- The skill required for the task.
- That agent's memory.
This makes the model replaceable. Slack provides the workplace and identity, your backend controls the workflow, and the AI provider supplies the reasoning and generation.
Step 7: Deploy and run an end to end test
Deploy the backend to a service that provides a public HTTPS URL. Add the resulting event endpoint to each Slack app's event subscription configuration.
Run this test with one agent:
- Create a dedicated test channel.
- Invite the agent's Slack app.
- Post a task using the Task specification in
agent-company.md. - Mention the agent if your selected Slack event requires a mention.
- Confirm that the backend receives and verifies the event.
- Confirm that the correct company context, role, skill, and memory are loaded.
- Confirm that the response appears in the intended channel or thread.
- Check that the response includes a status and a concrete deliverable.
- Give one piece of constructive feedback.
- Add that feedback to the relevant Corrections subsection in the file.
- Repeat the same task and verify that the agent applies the correction.
A useful first task is small, real, and easy to judge. Avoid testing with a vague request such as “help with marketing.” Use a complete task instead:
Task title: Review the Acme campaign brief Owner: Ava Slack channel: #ai-marketing Outcome: Produce an actionable campaign delivery plan. Context: The client wants a product launch campaign for existing customers. Inputs: The client brief attached in this thread. Required skill: Review a client brief Priority: High Due date: Friday at 3:00 PM Reviewer: Human owner Approval required: Yes Definition of done: 1. Every requested deliverable is listed. 2. Missing information is clearly identified. 3. The work is divided into ordered actions. 4. Each action has an owner and reviewer.
Step 8: Add delegation and reporting
After one agent works reliably, connect a second agent and test a handoff in a shared thread. For example, a product agent can define requirements and request a software agent's implementation review.
Use the Daily company activity report section to consolidate:
- Completed tasks.
- Active work.
- Blockers and failures.
- Decisions that need a human.
- Memory changes caused by feedback.
A visual command center is optional. If you build one, use the task fields already defined in agent-company.md: owner, skill, priority, due date, Slack channel, status, and reviewer. Keep the Markdown file as the operating specification even if task state is later stored in a database.
Operating rule
Treat each agent like a new employee. Give it context, a job description, procedural training, real work, and specific feedback. Do not expect reliable behavior from an identity and a model connection alone. The role, skills, and memory in agent-company.md are what turn the Slack app into a useful worker.
