# Skill & Agent Discovery

How TeamDay discovers skills, agents, and MCPs from multiple sources — Space directories, managed resources, and cloned repositories.

# Skill & Agent Discovery

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

## Table of Contents

- [What You'll Learn](#what-youll-learn)
- [Understanding Multi-Source Discovery](#understanding-multi-source-discovery)
- [Discovery Sources](#discovery-sources)
- [Creating Skills](#creating-skills)
- [Creating Agents](#creating-agents)
- [Configuring MCPs](#configuring-mcps)
- [Viewing Discovered Items](#viewing-discovered-items)
- [Priority and Deduplication](#priority-and-deduplication)
- [Best Practices](#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

## 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: Managed         SOURCE 2: Space .claude/   SOURCE 3: Repos  │
│  ┌──────────────────┐      ┌──────────────────┐      ┌────────────────┐ │
│  │ User-created     │      │ Agent-created    │      │ Cloned repos   │ │
│  │ Skills registry  │      │ space/.claude/   │      │ repo/.claude/  │ │
│  │ Assigned to char │      │ (mutable)        │      │ (git-synced)   │ │
│  └────────┬─────────┘      └────────┬─────────┘      └───────┬────────┘ │
│           │                         │                         │          │
│           └─────────────────────────┼─────────────────────────┘          │
│                                     ▼                                    │
│                   ┌───────────────────────────────┐                      │
│                   │ Discovery + Deduplication     │                      │
│                   │ - Priority: Space > Managed │                      │
│                   │ - Repos prefixed with path    │                      │
│                   └───────────────┬───────────────┘                      │
│                                   ▼                                      │
│                       Available to Agent                                 │
└─────────────────────────────────────────────────────────────────────────┘
```

**Why Multiple Sources?**

- **Managed (Firestore)**: Curated skills/agents you manage via the UI or API
- **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 registry
- Share skills across spaces via repos

## Discovery Sources

### 1. Managed (Firestore)

Skills and agents stored in Firestore are explicitly assigned to agents or Spaces.

**Characteristics:**
- Created via web app, CLI, or API
- Assigned to agents or Spaces
- Visibility controls (private/org/public)
- Credentials stored as encrypted Space secrets

**Examples:**
- Skills from the skills registry
- 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

```markdown
---
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

```markdown
---
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

```json
{
  "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

```json
{
  "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

```json
{
  "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:

```json
{
  "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

1. Open your space
2. Go to **Claude Config** tab (or similar)
3. 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 Managed
- Badge: 📦 Managed
- 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    [Managed]                 🎯       │ │
│ │ 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

1. **Space `.claude/`** - Highest priority
2. **Managed** - Medium priority
3. **Repository `.claude/`** - Lowest priority

### How Deduplication Works

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

Managed:            blog-writer (assigned to agent)
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/Managed 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.

### Conflict Resolution

When the same name exists in multiple sources:
- **Space version wins** — it has the highest priority
- **Repo versions are prefixed** — so `teamday-cc/blog-writer` coexists with `blog-writer`
- Managed and Space versions with the same name: Space overrides

## Best Practices

### 1. Use Repos for Shared Skills

Put reusable skills in Git repositories:

```bash
# 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. Use Space Secrets for Credentials

Store API keys and tokens as encrypted Space secrets:

```bash
teamday spaces set-secret <space-id> \
  BRAVE_API_KEY=your-key \
  GA_PROPERTY_ID=123456789
```

Reference them in `.mcp.json` with `${VAR_NAME}` syntax. See [Integrating External Services](https://docs.teamday.ai/guides/api-integration) for details.

### 4. Document Your Skills

Add clear descriptions and examples:

```markdown
---
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"
```

### 7. Use Prefixed Names Intentionally

If you want a repo skill to override others:
1. Copy it to space's `.claude/skills/`
2. Remove the prefix
3. It becomes highest priority

### 8. Monitor MCP Configurations

Check `.mcp.json` files for:
- Correct paths
- Valid credentials
- Appropriate timeouts
- Security best practices

## Troubleshooting

### Skills Not Appearing

**Check:**
1. File is named `SKILL.md` (case-sensitive)
2. Located in `.claude/skills/{name}/SKILL.md`
3. Valid YAML frontmatter
4. Click Refresh in UI

### Agents Not Discovered

**Check:**
1. File ends with `.md`
2. Located in `.claude/agents/`
3. Has `description` in frontmatter
4. Valid YAML syntax

### MCPs Not Loading

**Check:**
1. `.mcp.json` at root level
2. Valid JSON syntax
3. Command is installed/available
4. Environment variables set correctly

### Wrong Version Used

If the wrong version of a skill is being used:
1. Check priority order
2. Rename or remove conflicting versions
3. Use explicit prefixed names

## Next Steps

- **[MCP Plugins Guide](https://docs.teamday.ai/guides/mcp-plugins)** - Configure external tools
- **[Spaces Guide](https://docs.teamday.ai/guides/spaces)** - Workspace management
- **[Agent Configuration](https://docs.teamday.ai/guides/agent-configuration)** - Advanced settings
- **[Missions Guide](https://docs.teamday.ai/guides/missions-user-guide)** - Scheduled automation