Add agent harness documentation and agentic tools reference

[cmungall]

Summary

This PR adds comprehensive documentation for building and understanding agent harnesses — the infrastructure that wraps AI agents to make them reliable, auditable, and production-ready for curation workflows. It includes a new how-to guide, reference documentation, glossary updates, and FAQ entries.

Key Changes

• New how-to guide: docs/how-tos/build-agentic-harness.md — explains what an agent harness is, why curators need one, and how to assemble one from existing tools (system instructions, MCP servers, validators, provenance tracking, GitHub Actions, and human-in-the-loop controls)

• New reference page: docs/reference/agentic-tools.md — detailed documentation of available tools including validators (linkml-term-validator, linkml-reference-validator), provenance tools (ai-blame), agent skills (curation-skills), and MCP servers (noctua-mcp, oak-mcp)

• Glossary expansions: Added entries for:

  • Agent Harness (with link to new how-to guide)
  • ai-blame
  • Curation Skill
  • Provenance
  • linkml-reference-validator
  • linkml-term-validator
  • OAK (Ontology Access Kit)
  • Updated MCP entry with domain-specific server examples

• FAQ additions: New section on "Agent Harness and Infrastructure" covering what a harness is, validation tools, provenance tracking, and available MCP servers

• Enhanced how-tos: Added Tips 4-7 to integrate-ai-into-your-kb.md covering validation, provenance tracking, MCP servers, and thinking in terms of harnesses

• Updated examples page: Added "Agentic Infrastructure" section with examples of ai-blame, curation-skills, noctua-mcp, and ICBO 2025 AI tutorial

• Improved client apps reference: Converted docs/reference/client-apps.md from stub to full reference with comparison table and guidance on choosing clients

• Tutorial updates: Added "Additional training materials" section to ontology-editing-with-ai.md with links to workshops and recordings

• Navigation updates: Added new how-to guide to mkdocs.yml navigation structure

Notable Details

The documentation emphasizes that an agent harness is not the agent itself, but the control plane around it — the infrastructure that ensures reliability, consistency, and auditability. The guide provides a concrete composition diagram showing how system instructions, tools, validators, provenance tracking, lifecycle automation, and human oversight work together.

https://claude.ai/code/session_01M6GBwgQiNEwBMCaigvtEvH

[claude]

Claude finished @cmungall's task —— View job

---

PR Review: Add agent harness documentation and agentic tools reference

I've completed a comprehensive review of this documentation PR. The additions significantly enhance the project's value by providing comprehensive guidance on agent harness infrastructure.

Review Tasks:

• Read repository guidelines (CLAUDE.md)
• Review new documentation files
• Check existing file modifications
• Verify navigation and structure changes
• Assess documentation quality and consistency
• Provide constructive feedback

---

Overall Assessment: Excellent

This PR significantly elevates the documentation quality and provides substantial practical value to the target audience. The concept of an "agent harness" as infrastructure rather than the agent itself is well-articulated and fills a crucial gap in AI curation guidance.

Strengths

Content Quality:

• Clear conceptual framework: The distinction between agents and harnesses is well-explained and valuable
• Practical focus: Aligns perfectly with CLAUDE.md guidelines for "immediately actionable content"
• Comprehensive coverage: Addresses the full lifecycle from basic setup to advanced provenance tracking
• Real-world examples: Includes concrete GitHub repositories and working implementations

Documentation Structure:

• Logical organization: New content fits naturally into existing how-tos/reference structure
• Cross-references: Excellent linking between glossary, how-tos, and reference pages
• Visual clarity: The ASCII harness composition diagram effectively illustrates concepts
• Navigation integration: New content properly integrated into mkdocs.yml structure

Technical Accuracy:

• Current tools: References legitimate, actively maintained projects (ai-blame, linkml validators, MCP servers)
• Working links: All GitHub repositories and documentation links appear valid
• Consistent terminology: Proper use of established terms throughout

Areas for Improvement

Minor Issues:

1. Link consistency in docs/how-tos/build-agentic-harness.md:36,73:

   • References to instruct-github-agent.md and set-up-github-actions.md should verify these guides exist
   • Consider adding "coming soon" notes if guides are planned but not yet created

2. MCP server documentation in docs/reference/agentic-tools.md:59:

   • oak-mcp entry lacks installation and PyPI links (unlike noctua-mcp)
   • Consider adding these for consistency if available

3. Example validation in glossary and how-tos:

   • Some GitHub repository links should be verified for accuracy (particularly the CLAUDE.md examples in Mondo/Uberon)

Documentation Standards:

The content excellently follows the repository's documentation standards:

• ✅ Focuses on practical, actionable content over theory
• ✅ Provides step-by-step guidance with concrete examples
• ✅ Maintains consistency with Material theme patterns
• ✅ Targets practitioners needing immediate solutions

Code Quality Assessment

No security concerns identified - this is pure documentation with no executable code.

Performance considerations: Documentation-only changes have no runtime performance impact. The MkDocs build should handle the additional content without issues.

Test coverage: While this is documentation, the practical value can be validated by:

• Verifying all external links work
• Testing the mkdocs build locally
• Following the how-to guides to ensure they work as described

Best Practices Adherence

Excellent adherence to repository conventions:

• Follows existing file naming patterns
• Uses consistent markdown formatting
• Integrates properly with existing navigation structure
• Maintains the project's voice and style
• Adds value without disrupting existing workflows

Recommendation: Approve and Merge

This PR delivers significant value to the AI4Curators community with high-quality, practical documentation. The minor issues identified are suggestions for enhancement rather than blockers. The content is ready for production and will substantially help users understand and implement agent harnesses for reliable AI-assisted curation.

---

[Copilot]

Pull request overview

Adds new documentation describing “agent harnesses” (control-plane infrastructure around AI agents) and a reference catalog of agentic tools used in AI-assisted curation workflows, plus related navigation and supporting docs updates.

Changes:

• Added a new how-to guide for assembling an agentic harness and a new “agentic tools” reference page.
• Expanded glossary/FAQ/examples/tutorials to include harness concepts, tool references, and training materials.
• Updated MkDocs navigation and upgraded the “Client apps” page into a usable reference.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
mkdocs.yml	Adds the new how-to and reference pages to site navigation.
docs/how-tos/build-agentic-harness.md	New guide describing harness components and how they compose.
docs/reference/agentic-tools.md	New reference page cataloging validators, provenance tools, skills, and MCP servers.
docs/reference/client-apps.md	Replaces stub with a client comparison table and selection guidance.
docs/how-tos/integrate-ai-into-your-kb.md	Adds tips on validation, provenance, MCP servers, and harness framing.
docs/glossary.md	Adds new glossary entries for harness-related concepts and tools.
docs/faq.md	Adds an “Agent Harness and Infrastructure” FAQ section.
docs/examples.md	Adds “Agentic Infrastructure” examples (ai-blame, skills, MCP, tutorial).
docs/tutorials/ontology-editing-with-ai.md	Adds additional training materials and cross-links to harness guide.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The link text "CLAUDE.md" currently points to the glossary anchor for "Claude Code" (#claude-code), which is misleading for readers and makes it harder to find what CLAUDE.md is. Consider either changing the link text to "Claude Code" (if you meant the client) or linking CLAUDE.md to the relevant how-to (e.g., instruct-github-agent) or describing it as inline code without a link.

Suggested change

In a curation context, a harness typically includes: system instructions (e.g. [CLAUDE.md](#claude-code)), validators (e.g. [linkml-term-validator](#linkml-term-validator), [linkml-reference-validator](#linkml-reference-validator)), provenance tools (e.g. [ai-blame](#ai-blame)), [MCP](#model-context-protocol-mcp) servers for domain-specific tool access, and [GitHub Actions](#github-actions) for lifecycle automation.

In a curation context, a harness typically includes: system instructions (e.g. `CLAUDE.md`), validators (e.g. [linkml-term-validator](#linkml-term-validator), [linkml-reference-validator](#linkml-reference-validator)), provenance tools (e.g. [ai-blame](#ai-blame)), [MCP](#model-context-protocol-mcp) servers for domain-specific tool access, and [GitHub Actions](#github-actions) for lifecycle automation.