GitHub Copilot Customizations for Foam Knowledge Base

January 10, 2026 · View on GitHub

This directory contains custom agents, prompts, and instructions from GitHub's Awesome Copilot repository that enhance the Foam knowledge base experience with specialized capabilities for templates, documentation, and markdown content creation.

Overview

These customizations are specifically selected to work with:

  • Foam knowledge bases - Personal knowledge management system
  • Markdown content - Templates, notes, and documentation
  • Template functions - Dynamic content generation with Foam variables

Directory Structure

.github/
├── agents/           # Custom AI agents for specialized workflows
├── instructions/     # Project-wide coding standards and guidelines
├── prompts/          # Task-specific prompts for content generation
└── README.md        # This file

🤖 Custom Agents

Technical Writer Agent

File: agents/se-technical-writer.agent.md

A specialized agent for creating developer documentation, technical blogs, tutorials, and educational content.

Use cases:

  • Creating comprehensive documentation for your knowledge base
  • Writing technical blog posts and tutorials
  • Developing user guides and architecture decision records (ADRs)
  • Structuring content with proper markdown formatting

Key features:

  • Multiple content type templates (blogs, docs, tutorials, ADRs)
  • Audience adaptation (junior to senior developers)
  • Style and tone management
  • Quality checklist for documentation

When to use: Assign this agent to issues involving documentation creation, technical writing, or when you need to transform complex technical concepts into clear, accessible content.

📋 Instructions

Instructions automatically apply to files based on their patterns and provide contextual guidance.

Markdown Instructions

File: instructions/markdown.instructions.md
Applies to: **/*.md

Enforces markdown content standards including:

  • Proper heading hierarchy
  • Code block formatting
  • Link and image syntax
  • Table formatting
  • Front matter requirements

Agent Skills Instructions

File: instructions/agent-skills.instructions.md
Applies to: **/.github/skills/**/SKILL.md

Guidelines for creating portable Agent Skills with bundled resources that enhance AI capabilities for specialized tasks.

🎯 Prompts

Use the / command in GitHub Copilot Chat to access these prompts.

Documentation Writer

File: prompts/documentation-writer.prompt.md

Diátaxis Documentation Expert - Creates high-quality software documentation following the Diátaxis framework.

Usage:

/documentation-writer

Document types:

  • Tutorials: Learning-oriented practical steps
  • How-to Guides: Problem-oriented recipes
  • Reference: Technical descriptions and API docs
  • Explanation: Understanding-oriented discussions

Update Markdown File Index

File: prompts/update-markdown-file-index.prompt.md

Updates markdown file sections with an index/table of files from a specified folder.

Usage:

/update-markdown-file-index

Features:

  • Scans and analyzes folder structure
  • Generates tables or lists of files
  • Extracts descriptions from file headers
  • Updates existing indexes or creates new ones

Integration with Foam Templates

These agents and prompts work seamlessly with Foam's template system located in .foam/templates/:

  • new-note.md - Basic note template with $FOAM_TITLE variable
  • daily-note.md - Daily journal template with date variables
  • your-first-template.md - Example template with tabstops and variables

Foam Template Variables Supported

The technical writer agent and documentation prompts understand these Foam variables:

  • ${FOAM_TITLE} - Note title
  • ${FOAM_TITLE_SAFE} - URL-safe version of title
  • ${FOAM_CURRENT_DIR} - Current directory path
  • ${FOAM_DATE_YEAR}, ${FOAM_DATE_MONTH}, ${FOAM_DATE_DATE} - Date components
  • ${CURRENT_YEAR}, ${CURRENT_MONTH}, ${CURRENT_DATE} - VS Code date variables

How to Use

In VS Code

  1. Custom Agents: When working on documentation, mention the technical writer agent in your Copilot chat
  2. Prompts: Use / command to access available prompts
  3. Instructions: These apply automatically when editing markdown files

With Copilot Coding Agent (CCA)

When assigning an issue to Copilot:

  1. Select the "SE: Tech Writer" agent from the custom agent list
  2. The agent will apply specialized documentation creation capabilities
  3. Use for issues tagged with documentation, template, or writing

Creating New Templates

To create new Foam templates with these agents:

  1. Use the technical writer agent to draft template content
  2. Add Foam template frontmatter: 
    ---
foam_template:
  filepath: "$FOAM_CURRENT_DIR/$FOAM_TITLE_SAFE.md"
  description: "Template description"
---
  3. Use VS Code snippet syntax for tabstops: ${1:First field}
  4. Save in .foam/templates/ directory

Best Practices

For Documentation

  • Follow the Diátaxis framework (tutorials, how-tos, reference, explanation)
  • Use clear heading hierarchy (H2, H3 - avoid H1)
  • Include code blocks with language identifiers
  • Add alt text to images for accessibility

For Templates

  • Keep templates focused and single-purpose
  • Use descriptive variable names
  • Add inline comments to guide users
  • Test templates before adding to the repository

For Knowledge Management

  • Use consistent naming conventions
  • Link related notes together
  • Maintain an index of important documents
  • Regular review and update of outdated content

Contributing New Agents

To add more agents from awesome-copilot:

  1. Browse the awesome-copilot repository
  2. Identify agents relevant to knowledge management, markdown, or documentation
  3. Copy relevant files to appropriate directories:
    • Agents → .github/agents/
    • Instructions → .github/instructions/
    • Prompts → .github/prompts/
  4. Update this README with usage information
  5. Test the new customizations with your Foam workflow

Resources

License

These agent files are sourced from the github/awesome-copilot repository and maintain their original licenses. Please refer to the awesome-copilot repository for detailed license information.