Skill & Agent Discovery

Learn how TeamDay automatically discovers and merges skills, agents, and MCP configurations from multiple sources for use by your AI agents.

What You'll Learn
Understanding Multi-Source Discovery
Discovery Sources
Creating Skills
Creating Agents
Configuring MCPs
Viewing Discovered Items
Priority and Deduplication
Best Practices

What You'll Learn

By the end of this guide, you'll know how to:

✅ Understand how TeamDay discovers skills, agents, and MCPs
✅ Create skills in .claude/skills/ directories
✅ Create agents in .claude/agents/ directories
✅ Configure MCPs using .mcp.json files
✅ View all discovered items in the Space UI
✅ Understand priority order and deduplication

Time to complete: 20-30 minutes

Understanding Multi-Source Discovery

TeamDay agents can use skills (invokable capabilities), subagents (specialized agents), and MCPs (external tool integrations) from multiple sources:

┌─────────────────────────────────────────────────────────────────────────┐
│                    DISCOVERY SOURCES                                     │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  SOURCE 1: Firebase         SOURCE 2: Space .claude/   SOURCE 3: Repos  │
│  ┌──────────────────┐      ┌──────────────────┐      ┌────────────────┐ │
│  │ User-created     │      │ Agent-created    │      │ Cloned repos   │ │
│  │ Marketplace      │      │ space/.claude/   │      │ repo/.claude/  │ │
│  │ Assigned to char │      │ (mutable)        │      │ (git-synced)   │ │
│  └────────┬─────────┘      └────────┬─────────┘      └───────┬────────┘ │
│           │                         │                         │          │
│           └─────────────────────────┼─────────────────────────┘          │
│                                     ▼                                    │
│                   ┌───────────────────────────────┐                      │
│                   │ Discovery + Deduplication     │                      │
│                   │ - Priority: Space > Firebase  │                      │
│                   │ - Repos prefixed with path    │                      │
│                   └───────────────┬───────────────┘                      │
│                                   ▼                                      │
│                       Available to Agent                                 │
└─────────────────────────────────────────────────────────────────────────┘

Why Multiple Sources?

Firebase: Curated skills/agents you manage via the UI
Space .claude/: Items created by agents during execution
Cloned Repos: Skills/agents that come with your codebases

This allows you to:

Import skills from Git repositories
Let agents create new skills during work
Manage curated skills via the marketplace
Share skills across spaces via repos

Discovery Sources

1. Firebase (Managed)

Skills and agents stored in Firebase are explicitly assigned to characters or spaces.

Characteristics:

Created via UI or API
Assigned to characters/spaces
Visibility controls (private/org/public)
Stored with credentials for MCPs

Examples:

Skills from the marketplace
Custom skills you create
MCP instances you configure

2. Space `.claude/` Directory

The space's root .claude/ directory contains items created directly in the workspace.

Location:

/sandbox/{orgId}/spaces/s-{spaceId}/
├── .claude/
│   ├── skills/
│   │   └── my-skill/
│   │       └── SKILL.md
│   └── agents/
│       └── my-agent.md
├── .mcp.json              # Space MCP config
└── ...your files...

Characteristics:

Highest priority (overrides other sources)
Mutable - agents can create/modify
Persists across executions
Not prefixed (uses name directly)

3. Cloned Repository `.claude/` Directories

When you clone a Git repository into your space, any .claude/ directories within it are automatically discovered.

Location:

/sandbox/{orgId}/spaces/s-{spaceId}/
├── my-cloned-repo/
│   ├── .claude/
│   │   ├── skills/
│   │   │   └── repo-skill/
│   │   │       └── SKILL.md
│   │   └── agents/
│   │       └── repo-agent.md
│   └── .mcp.json          # Repo MCP config
└── another-repo/
    └── .claude/
        └── skills/
            └── another-skill/
                └── SKILL.md

Characteristics:

Prefixed with repo path (e.g., my-cloned-repo/repo-skill)
Read-only from agent perspective (git-managed)
Lowest priority
Great for sharing skills via Git

Creating Skills

Skills are invokable capabilities that agents can use via the Skill tool.

Skill File Structure

Create a skill by adding a SKILL.md file in a skill directory:

.claude/skills/
└── blog-writer/
    ├── SKILL.md          # Required: skill definition
    └── scripts/          # Optional: helper scripts
        └── generate.sh

SKILL.md Format

---
description: "Write engaging blog posts with SEO optimization"
allowed-tools: ["Read", "Write", "WebSearch"]
---

You are an expert blog writer specializing in technical content.

When writing blog posts:
1. Research the topic thoroughly
2. Create an engaging outline
3. Write in a conversational tone
4. Include code examples where relevant
5. Optimize for SEO

## Output Format

Always output the blog post in Markdown format with:
- Clear headings (H1 for title, H2 for sections)
- Code blocks with language syntax highlighting
- A "Key Takeaways" section at the end

Frontmatter Fields

Field	Required	Description
`description`	Yes	Brief description shown in skill list
`allowed-tools`	No	Tools the skill can use (array)
`name`	No	Display name (defaults to folder name)

Example: Research Skill

---
description: "Deep research using web search and analysis"
allowed-tools: ["WebSearch", "WebFetch", "Read", "Write"]
---

You are a research assistant. When asked to research a topic:

1. **Search Phase**
   - Use WebSearch to find relevant sources
   - Gather at least 5 authoritative sources

2. **Analysis Phase**
   - Read and summarize each source
   - Identify key themes and insights
   - Note conflicting information

3. **Synthesis Phase**
   - Write a comprehensive summary
   - Include citations for all claims
   - Highlight areas needing more research

## Output Format

```markdown
# Research: {Topic}

## Summary
{2-3 paragraph overview}

## Key Findings
- Finding 1 [Source]
- Finding 2 [Source]

## Sources
1. {Title} - {URL}


## Creating Agents

Agents (subagents) are specialized Claude instances that can be spawned via the Task tool.

### Agent File Format

Create agents as `.md` files in the `agents/` directory:

.claude/agents/ ├── code-reviewer.md ├── test-writer.md └── documentation.md


### Agent Markdown Format

```markdown
---
name: code-reviewer
description: "Reviews code for quality, security, and best practices"
tools: Read, Grep, Glob
model: sonnet
---

You are an expert code reviewer. When reviewing code:

1. **Security Check**
   - Look for injection vulnerabilities
   - Check for hardcoded secrets
   - Verify input validation

2. **Quality Check**
   - Review naming conventions
   - Check for code duplication
   - Assess readability

3. **Performance Check**
   - Identify potential bottlenecks
   - Check for unnecessary operations
   - Review database queries

## Output Format

Provide feedback as:

```markdown
## Code Review: {filename}

### Security Issues
- [ ] Issue description (severity: high/medium/low)

### Quality Suggestions
- Suggestion with code example

### Performance Notes
- Observation and recommendation


### Frontmatter Fields

| Field | Required | Description |
|-------|----------|-------------|
| `name` | No | Agent name (defaults to filename) |
| `description` | Yes | Brief description for agent list |
| `tools` | No | Comma-separated list of allowed tools |
| `model` | No | Model to use (sonnet, opus, haiku) |

### Example: Test Writer Agent

```markdown
---
name: test-writer
description: "Writes comprehensive unit and integration tests"
tools: Read, Write, Bash, Glob
---

You are a test writing specialist. When asked to write tests:

1. **Analyze the Code**
   - Read the source file
   - Identify all public functions/methods
   - Note dependencies and edge cases

2. **Plan Test Cases**
   - Happy path scenarios
   - Error conditions
   - Edge cases
   - Boundary values

3. **Write Tests**
   - Use the project's testing framework
   - Follow existing test patterns
   - Include descriptive test names

4. **Verify**
   - Run the tests
   - Ensure all pass
   - Check coverage

## Testing Standards

- Each function should have at least 3 tests
- Test names should describe the scenario
- Mock external dependencies
- Use descriptive assertion messages

Configuring MCPs

MCPs (Model Context Protocol) extend agent capabilities with external tools. They can be configured via .mcp.json files.

.mcp.json Location

Place .mcp.json at the root of your space or repository:

space/
├── .mcp.json              # Space-level MCPs
└── my-repo/
    └── .mcp.json          # Repo-level MCPs

.mcp.json Format

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@package/mcp-server"],
      "env": {
        "API_KEY": "your-key"
      },
      "timeout": 30000
    }
  }
}

Configuration Fields

Field	Required	Description
`command`	Yes	Command to run (e.g., `npx`, `pipx`)
`args`	No	Arguments array
`env`	No	Environment variables
`timeout`	No	Startup timeout in ms

Example: Google Analytics MCP

{
  "mcpServers": {
    "google-analytics": {
      "command": "pipx",
      "args": ["run", "analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/credentials.json",
        "GOOGLE_PROJECT_ID": "my-project"
      },
      "timeout": 30000
    }
  }
}

Example: Multiple MCPs

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your-brave-api-key"
      }
    }
  }
}

SSE/HTTP MCPs

For server-based MCPs:

{
  "mcpServers": {
    "remote-mcp": {
      "type": "sse",
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer token"
      }
    }
  }
}

Viewing Discovered Items

TeamDay provides a UI to view all discovered skills, agents, and MCPs in your space.

Accessing the Discovery View

Open your space
Go to Claude Config tab (or similar)
View tabs: Skills, Agents, MCPs

Understanding the Display

Items are grouped by source:

Space Section

Items from {space}/.claude/
Badge: ✨ Space
Highest priority

Managed Section

Items from Firebase
Badge: 📦 Firebase
User-configured

Repositories Section

Items from cloned repos
Badge: 📂 {repo-name}
Prefixed with repo path

Example View

┌─────────────────────────────────────────────────────────────────────┐
│ Claude Config                                                        │
├───────────┬─────────────────────────────────────────────────────────┤
│ [Skills]  │ [Agents] │ [MCPs]                                       │
├───────────┴──────────┴──────────────────────────────────────────────┤
│                                                                      │
│ SPACE                                                                │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ ✨ custom-analyzer          [Space]                    🎯       │ │
│ │ Analyzes code patterns and suggests improvements                │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│                                                                      │
│ MANAGED                                                              │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 📦 blog-image-generation    [Firebase]                 🎯       │ │
│ │ Generate AI images for blog posts                               │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│                                                                      │
│ REPOSITORIES                                                         │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 📂 teamday-cc/research      [teamday-cc]               🎯       │ │
│ │ Deep research using web search                                  │ │
│ │ /teamday-cc/.claude/skills/research/SKILL.md                    │ │
│ └─────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘

Refreshing Discovery

Click the Refresh button to re-scan for new items after:

Cloning a new repository
Creating new skill/agent files
Modifying .mcp.json

Priority and Deduplication

When the same skill/agent/MCP exists in multiple sources, TeamDay uses priority-based deduplication.

Priority Order

Space .claude/ - Highest priority
Firebase - Medium priority
Repository .claude/ - Lowest priority

How Deduplication Works

Example: "blog-writer" skill exists in multiple places

Firebase:           blog-writer (assigned to character)
Space:              blog-writer (created by agent)
Repo teamday-cc:    blog-writer (from repo)

Result:
✓ blog-writer         → Uses Space version (highest priority)
✓ teamday-cc/blog-writer → Repo version available with prefix

Naming Conventions

Space/Firebase items: Use name directly (e.g., blog-writer)
Repo items: Prefixed with repo path (e.g., teamday-cc/blog-writer)

This ensures repo skills don't accidentally override your managed skills.

Content Hash

TeamDay uses content hashing to identify truly duplicate items:

Hash = SHA256(name + description + prompt)
Items with same hash from different sources are deduplicated
Space version takes precedence

Best Practices

1. Use Repos for Shared Skills

Put reusable skills in Git repositories:

# Create skills repo
mkdir my-skills
cd my-skills
git init
mkdir -p .claude/skills/research
# Add SKILL.md files
git add .
git commit -m "Add research skill"
git push origin main

Then clone into any space to use them.

2. Let Agents Create Skills

Agents can create new skills during execution:

User: "Create a skill for writing release notes"

Agent: [Creates .claude/skills/release-notes/SKILL.md]

Done! The release-notes skill is now available.

These persist in the space's .claude/ directory.

3. Keep Firebase for Credentials

Use Firebase MCPs for tools requiring credentials:

OAuth tokens (Google Analytics)
API keys (Brave Search)
Service accounts (BigQuery)

Firebase stores credentials securely.

4. Document Your Skills

Add clear descriptions and examples:

---
description: "Generate weekly analytics reports with charts and insights"
---

# Analytics Report Generator

## Usage

Invoke this skill when you need to:
- Create weekly performance reports
- Analyze traffic trends
- Generate executive summaries

## Example

"Generate the weekly analytics report for last week"

5. Version Control with Git

Keep your skills in Git:

Track changes over time
Share across team
Roll back if needed
Review skill modifications

6. Test Skills Before Deploying

Test in a development space first:

User: "Test the new research skill by researching 'TypeScript 5.0 features'"

Agent: [Uses research skill]
[Provides comprehensive research]

User: "Great, commit this skill"