Agent Discovery Tools

A practical guide to setting up and using the Agent Discovery Skills to document, standardize, and plan work across your projects.

These skills turn tribal knowledge into structured, AI-readable documentation. They work best in multi-module / microservices repositories but apply equally well to single-repo projects.

---

Table of Contents

1. Overview
2. MCP Server Setup
3. Installing the Skills
4. Usage Flow
5. The Four Core Skills
6. Running the Skills
7. Multi-Module vs Single-Repo
8. Best Practices
9. Troubleshooting

---

Overview

The toolkit consists of four core skills that should be executed in order:

#	Skill	Purpose	Output
1	Describe Architecture	Document what each service does, its tech stack, and integrations	AGENTS.md + ARCHITECTURE.md per module
2	Discover Standards	Extract tribal knowledge and coding patterns from the codebase	.agents/rules/standards/ per module
3	Unify Standards	Merge per-module standards into shared, org-wide rules	Root .agents/rules/standards/
4	Shape Spec	Plan new features using all gathered context	.agents/local/specs/

Each skill builds on the output of the previous one — describe gives the AI context about what exists, discover captures how your team writes code, unify promotes the best patterns across projects, and shape leverages all of that to plan new work.

---

MCP Server Setup

The skills rely on two MCP (Model Context Protocol) servers to connect your AI assistant to GitHub, Jira, and Confluence. Setting up both is strongly recommended — without them, the skills can still analyze your code, but they lose the ability to fetch Jira cards, Confluence docs, and GitHub context automatically.

GitHub MCP Server

GitHub's official MCP server connects Copilot to repos, issues, PRs, and code search.

Step 1 — Create a Personal Access Token

Go to github.com/settings/personal-access-tokens/new and create a fine-grained token. Enable permissions for the repos you want the AI to access (at minimum: Contents, Issues, Pull requests — read access).

Step 2 — Add to VS Code

Open Settings (JSON) (Cmd + Shift + P → Preferences: Open User Settings (JSON)) and add:

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "github_token",
        "description": "GitHub Personal Access Token",
        "password": true
      }
    ],
    "servers": {
      "github": {
        "command": "docker",
        "args": [
          "run", "-i", "--rm",
          "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
          "ghcr.io/github/github-mcp-server"
        ],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}"
        }
      }
    }
  }
}

Alternative — workspace-level config (shareable with the team): create .vscode/mcp.json in your repo with the same content inside "servers" (without the outer "mcp" key).

Tip: If your organization uses GitHub Enterprise Server, add "GITHUB_HOST": "github.your-company.com" to the env block.

Atlassian MCP Server (Jira + Confluence)

The mcp-atlassian package provides Jira and Confluence access through a single server. This is the package used by the jira-assistant and confluence-assistant skills.

Step 1 — Create an Atlassian API Token

Go to id.atlassian.com/manage-profile/security/api-tokens and create a token.

Step 2 — Add to VS Code

In the same mcp.servers section of your settings, add:

{
  "mcp-atlassian": {
    "command": "uvx",
    "args": ["mcp-atlassian"],
    "env": {
      "JIRA_URL": "https://your-company.atlassian.net",
      "JIRA_USERNAME": "your.email@company.com",
      "JIRA_API_TOKEN": "your_api_token",
      "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
      "CONFLUENCE_USERNAME": "your.email@company.com",
      "CONFLUENCE_API_TOKEN": "your_api_token"
    }
  }
}

Server/Data Center users: Replace JIRA_USERNAME + JIRA_API_TOKEN with JIRA_PERSONAL_TOKEN. See the mcp-atlassian docs for details.

Verifying the Setup

1. Open VS Code and switch Copilot Chat to Agent mode (click the mode selector at the bottom of the chat input)
2. Type: @github what repos do I have access to? — you should see results from the GitHub MCP
3. Type: search Confluence for onboarding — you should see Confluence results
4. If either fails, check the MCP server logs in the Output panel (View → Output → MCP)

---

Installing the Skills

Option A — Clone this repository (recommended for teams)

git clone https://github.com/hm-group/agent-discovery-tools.git

Copy the .agents/skills/ folder into your target project:

cp -r agent-discovery-tools/.agents/skills/ /path/to/your-project/.agents/skills/

Option B — Git submodule (keeps skills updatable)

cd /path/to/your-project
git submodule add https://github.com/hm-group/agent-discovery-tools.git .agents/discovery-tools

Then symlink or reference the skills from .agents/discovery-tools/.agents/skills/.

Verify Installation

Your project should have this structure:

your-project/
├── .agents/
│   └── skills/
│       ├── describe-architecture/
│       │   └── SKILL.md
│       ├── discover-standards/
│       │   └── SKILL.md
│       ├── unify-standards/
│       │   └── SKILL.md
│       ├── shape-spec/
│       │   └── SKILL.md
│       ├── confluence-assistant/    # supporting skill
│       │   └── SKILL.md
│       ├── jira-assistant/          # supporting skill
│       │   └── SKILL.md
│       └── coding-guidelines/       # supporting skill
│           └── SKILL.md
├── service-a/
├── service-b/
└── ...

---

Usage Flow

The diagram below illustrates the recommended execution flow. Each skill feeds into the next, building a progressively richer context for your AI assistant.

flowchart TD
    Start([Start Here]) --> HasModules{Multi-module<br/>repository?}

    HasModules -->|Yes| PickModule["Pick a module<br/>(e.g. order-service)"]
    HasModules -->|No| SingleRepo["Target the root<br/>repository"]

    PickModule --> Describe
    SingleRepo --> Describe

    subgraph "Phase 1 — Document"
        Describe["① Describe Architecture<br/><i>generates AGENTS.md +<br/>ARCHITECTURE.md</i>"]
    end

    Describe --> MoreModules{More modules<br/>to describe?}
    MoreModules -->|Yes| PickModule
    MoreModules -->|No| DiscoverStart

    subgraph "Phase 2 — Extract"
        DiscoverStart["Pick a module"] --> Discover["② Discover Standards<br/><i>extracts tribal knowledge<br/>into .agents/rules/standards/</i>"]
        Discover --> MoreAreas{More focus<br/>areas?}
        MoreAreas -->|Yes| Discover
        MoreAreas -->|No| MoreDiscover{More modules<br/>to discover?}
        MoreDiscover -->|Yes| DiscoverStart
    end

    MoreDiscover -->|No| CheckMulti{Multiple modules<br/>discovered?}

    CheckMulti -->|Yes| Unify
    CheckMulti -->|No, single repo| Shape

    subgraph "Phase 3 — Consolidate"
        Unify["③ Unify Standards<br/><i>merges per-module rules<br/>into shared org standards</i>"]
    end

    Unify --> Shape

    subgraph "Phase 4 — Plan"
        Shape["④ Shape Spec<br/><i>gathers all context to<br/>plan new features</i>"]
    end

    Shape --> Implement([Ready to Implement])

    %% External sources
    Jira[(Jira)] -.->|cards, epics| Describe
    Jira -.->|requirements| Shape
    Confluence[(Confluence)] -.->|design docs| Describe
    Confluence -.->|architecture pages| Shape
    Code[(Codebase)] -.->|analysis| Describe
    Code -.->|patterns| Discover
    Code -.->|reference impl| Shape

    style Describe fill:#4A90D9,color:#fff
    style Discover fill:#7B68EE,color:#fff
    style Unify fill:#E67E22,color:#fff
    style Shape fill:#2ECC71,color:#fff
    style Start fill:#95A5A6,color:#fff
    style Implement fill:#27AE60,color:#fff

Loading

Simplified View (Linear)

For a quick mental model, the flow is:

Describe → Discover → Unify → Shape → Implement
   ↑           ↑         ↑        ↑
   └───────────┴─────────┴────────┘
        Jira + Confluence + Codebase

---

The Four Core Skills

1. Describe Architecture

What it does: Generates AGENTS.md (agent configuration) and ARCHITECTURE.md (technical documentation) for each microservice/module by analyzing code and pulling context from Confluence and Jira.

When to run: First. Run once per module to establish a baseline.

Trigger phrases:

• "describe architecture"
• "document microservice"
• "generate AGENTS.md for order-service"

What it produces:

service-a/
└── .agents/
    ├── AGENTS.md           # Jira config, Confluence refs, overview, output preferences
    └── memories/
        └── ARCHITECTURE.md # Tech stack, package structure, APIs, data flow, deployment

2. Discover Standards

What it does: Reads representative code files in a focus area (API, domain, testing, etc.), identifies patterns that are unusual, opinionated, or tribal, and writes them as concise standard files.

When to run: After describe. Run per module, per focus area.

Trigger phrases:

• "discover standards"
• "find coding standards in order-service"
• "extract conventions"

What it produces:

service-a/
└── .agents/
    └── rules/
        └── standards/
            ├── index.yml
            ├── api/
            │   └── response-envelope.md
            ├── domain/
            │   └── immutable-models.md
            └── testing/
                └── wiremock-pattern.md

3. Unify Standards

What it does: Scans all per-module standards, scores them by usage/simplicity/distinctiveness, groups similar rules across projects, and merges them into shared org-wide standards at the root level.

When to run: After you've discovered standards in at least 2+ modules.

Trigger phrases:

• "unify standards"
• "merge rules"
• "consolidate standards"

What it produces:

your-project/
└── .agents/
    └── rules/
        └── standards/          # root-level unified standards
            ├── index.yml
            ├── api/
            │   └── structured-logging.md
            ├── domain/
            │   └── immutable-domain-models.md
            └── testing/
                └── wiremock-external-apis.md

4. Shape Spec

What it does: Gathers context from .agents/ directories, Jira, and Confluence to plan and structure a feature spec before implementation begins. Reads architecture docs, relevant standards, and reference implementations to create an actionable plan.

When to run: When starting significant new work. Requires plan mode in Copilot.

Trigger phrases:

• "shape spec"
• "plan feature"
• "shape this work"

What it produces:

your-project/
└── .agents/
    └── local/
        └── specs/
            └── PROJ-1234-user-comments/
                ├── plan.md         # Full implementation plan
                ├── shape.md        # Scope, decisions, context
                ├── context.md      # Gathered from .agents/, Jira, Confluence
                ├── standards.md    # Applicable standards
                ├── references.md   # Similar code pointers
                └── visuals/        # Mockups (if any)

---

Running the Skills

All skills are triggered through Copilot Chat in Agent mode. Switch to Agent mode by clicking the mode selector below the chat input.

Step-by-step: Full workflow on a multi-module project

Round 1 — Describe each module

You: describe architecture for order-service

The agent will:

1. Ask you to add context sources (Confluence pages, Jira epics, descriptions)
2. Scan the codebase automatically
3. Ask for Jira/Confluence configuration values
4. Generate and confirm AGENTS.md and ARCHITECTURE.md

Repeat for each module (payment-gateway, inventory-sync, etc.).

Round 2 — Discover standards per module

You: discover standards in order-service

The agent will:

1. Present focus areas found in the codebase (API, domain, testing, etc.)
2. Show patterns it detected within the chosen area
3. Ask "why" for each pattern to capture the reasoning
4. Draft and confirm each standard file

Repeat for each module and each relevant focus area.

Round 3 — Unify across modules

You: unify standards

The agent will:

1. Find all per-module .agents/rules/standards/ directories
2. Score and group similar rules
3. Present merged drafts for your approval (one by one)
4. Write approved rules to the root .agents/rules/standards/

Round 4 — Shape new work

Switch to plan mode first, then:

You: shape spec for PROJ-1234

The agent will:

1. Fetch the Jira card and any linked Confluence pages
2. Read .agents/ context from root and target module
3. Ask for visuals and reference implementations
4. Surface applicable standards
5. Generate a full spec folder with plan, context, and standards

---

Multi-Module vs Single-Repo

Multi-module repository (recommended scenario)

monorepo/
├── .agents/                  # root-level: shared config + unified standards
│   ├── AGENTS.md
│   ├── rules/standards/      # ← output of "unify"
│   └── skills/               # ← the skills themselves
├── order-service/
│   └── .agents/              # module-level: per-service docs + standards
│       ├── AGENTS.md         # ← output of "describe"
│       ├── memories/
│       │   └── ARCHITECTURE.md
│       └── rules/standards/  # ← output of "discover"
├── payment-gateway/
│   └── .agents/
│       └── ...
└── inventory-sync/
    └── .agents/
        └── ...

Run describe and discover per module, then unify once at the root.

Single repository

my-app/
├── .agents/
│   ├── AGENTS.md             # ← output of "describe"
│   ├── memories/
│   │   └── ARCHITECTURE.md
│   ├── rules/standards/      # ← output of "discover" (no unify needed)
│   └── skills/
└── src/
    └── ...

Run describe once, discover per focus area. Skip unify (nothing to merge). Go straight to shape.

---

Best Practices

MCP Configuration

• Set up both Atlassian and GitHub MCP servers. The skills degrade gracefully without them, but you lose the ability to pull Jira requirements and Confluence design docs automatically.
• Use workspace-level .vscode/mcp.json to share MCP config across the team (tokens stay local as input prompts).
• Keep API tokens out of version control. Use the ${input:...} prompt pattern or environment variables.

Skill Execution

• Follow the order: Describe → Discover → Unify → Shape. Each skill builds on the output of the previous.
• Run Describe first on every new module before doing anything else — it creates the .agents/AGENTS.md that all other skills depend on.
• Discover one area at a time. Don't try to extract all standards in one session. Focus on API, then domain, then testing, etc.
• Review the AI's drafts carefully. The skills ask for confirmation at every step. Use that to correct inaccuracies.
• Commit .agents/ outputs to version control. This is documentation — it should evolve with the code.

Documentation Quality

• Keep standards concise. They are injected into AI context windows. Every unnecessary word costs tokens and reduces quality.
• Lead with the rule, explain "why" second. AI agents scan for actionable instructions.
• Use code examples in standards. "Show, don't tell" is even more important for AI readers.
• Update docs when code changes. Re-run describe/discover periodically (e.g., after major refactors).

---

Troubleshooting

Problem	Solution
MCP server not starting	Check Docker is running (GitHub) or uvx is installed (Atlassian). Look at View → Output → MCP for logs.
"Shape-spec must be run in plan mode"	Switch to plan mode in Copilot Chat before running shape-spec.
Skills not recognized by Copilot	Verify .agents/skills/*/SKILL.md files exist in your workspace root. Restart VS Code.
Atlassian token rejected	Regenerate at id.atlassian.com. Ensure the token user has access to the Jira/Confluence spaces.
"No per-project standards found" during unify	Run discover-standards on at least 2 modules first.
Discover finds too many / too few patterns	Narrow or broaden the focus area. You can also suggest patterns manually.