### Project Installation Steps Source: https://github.com/agentbrazley/dot.agent/blob/main/RELEASE_NOTES.md Commands to clone the repository, install dependencies, build the project, and optionally link the CLI globally for development. ```bash # Clone the repository git clone https://github.com/YOUR_USERNAME/dot.agent.git cd dot.agent # Install dependencies npm install # Build the project npm run build # Link CLI globally (optional) npm link ``` -------------------------------- ### Install agent-frontmatter Library Source: https://github.com/agentbrazley/dot.agent/blob/main/README.md Instructions for installing the `agent-frontmatter` library as a project dependency using either npm or yarn, enabling its use within your applications. ```bash npm install agent-frontmatter # or yarn add agent-frontmatter ``` -------------------------------- ### Install agent-frontmatter CLI Globally Source: https://github.com/agentbrazley/dot.agent/blob/main/README.md Command to install the `agent-frontmatter` command-line interface globally, making its utilities accessible from any directory in your terminal. ```bash npm install -g agent-frontmatter ``` -------------------------------- ### Example Agent File with YAML Frontmatter Source: https://github.com/agentbrazley/dot.agent/blob/main/README.md A sample markdown file demonstrating the structure of an AI agent file, including its YAML frontmatter metadata. This example specifies the agent's name, version, description, capabilities, coding languages, and frameworks. ```yaml ---agent: name: "Python Data Assistant" version: "1.0.0" description: "Helps with Python data analysis and visualization" capabilities: ["data-analysis", "visualization", "machine-learning"] coding_languages: ["python"] frameworks: ["pandas", "matplotlib", "scikit-learn"] --- # Python Data Assistant I'm here to help you with data analysis tasks... ``` -------------------------------- ### Example .agent File Structure Source: https://github.com/agentbrazley/dot.agent/blob/main/RELEASE_NOTES.md Illustrates the basic structure of an .agent file, including YAML frontmatter for metadata and the main content section for agent documentation and implementation details. ```yaml --- name: MyAgent version: 1.0.0 description: An example agent author: Your Name capabilities: - text-generation - code-analysis --- # Agent Content Your agent documentation and implementation details go here. ``` -------------------------------- ### Minimal Agent File YAML Schema Example Source: https://github.com/agentbrazley/dot.agent/blob/main/README.md A simplified YAML frontmatter example showcasing the absolute minimum required structure for an agent file. This snippet demonstrates that only the agent's name is mandatory within the `agent` block. ```yaml ---agent: name: "My Assistant" --- # My Assistant Assistant content here... ``` -------------------------------- ### Agent File Structure Example Source: https://github.com/agentbrazley/dot.agent/blob/main/docs/schema.md Illustrates the basic structure of an `.agent` file, showing the YAML frontmatter delimited by `---` and followed by optional Markdown content. ```YAML --- # YAML frontmatter with agent metadata name: AgentName version: 1.0.0 # ... other fields --- # Optional Markdown content Agent documentation, instructions, or implementation details. ``` -------------------------------- ### agent-frontmatter CLI Commands Source: https://github.com/agentbrazley/dot.agent/blob/main/README.md Examples of various `agent-lint` command-line interface operations. These commands demonstrate how to validate single or multiple agent files, lint and auto-fix common issues, check compatibility, and display detailed information about an agent file. ```bash # Validate a single agent file agent-lint validate my-agent.md # Lint multiple files agent-lint lint "agents/**/*.md" # Auto-fix common issues agent-lint lint --fix # Check compatibility agent-lint check-compat my-agent.md --model claude-3 --context 200000 # Display agent information agent-lint info my-agent.md ``` -------------------------------- ### CLI Tool Usage Examples Source: https://github.com/agentbrazley/dot.agent/blob/main/RELEASE_NOTES.md Demonstrates basic command-line operations for validating and linting .agent files using the agent-validator tool. ```bash agent-validator validate myagent.agent agent-validator lint --fix myagent.agent ``` -------------------------------- ### Display All Metadata for .agent File Source: https://github.com/agentbrazley/dot.agent/blob/main/docs/macos-file-type-registration.md This command uses `mdls` to display all available metadata for an `example.agent` file. It's useful for a comprehensive verification of how macOS is indexing and understanding the file after the `.agent` file type registration. ```bash mdls example.agent ``` -------------------------------- ### Project Development Workflow Commands Source: https://github.com/agentbrazley/dot.agent/blob/main/README.md This section outlines essential bash commands for setting up the development environment, building the project, running automated tests, starting the project in development mode, and performing code linting. These commands are crucial for local development and continuous integration workflows. ```bash # Install dependencies npm install # Build npm run build # Run tests npm test # Development mode npm run dev # Lint npm run lint ``` -------------------------------- ### Terminate Quick Look UI Service Source: https://github.com/agentbrazley/dot.agent/blob/main/docs/macos-file-type-registration.md This command forcefully terminates the `QuickLookUIService` process. Restarting this service can resolve persistent Quick Look display issues by ensuring a fresh start for the Quick Look UI components. ```bash killall -KILL QuickLookUIService ``` -------------------------------- ### Complete Agent Definition YAML Example Source: https://github.com/agentbrazley/dot.agent/blob/main/README.md A comprehensive YAML configuration for a 'Python Data Science Assistant', detailing its identity, technical capabilities, domain expertise, model requirements, authorship, and discovery metadata. This structure defines how an agent is characterized and its operational parameters. ```yaml --- agent: # Required name: "Python Data Science Assistant" version: "2.1.0" # Core Identity description: "Specialized assistant for data analysis and ML workflows" role: "Data Science Assistant" specialization: "Statistical Analysis & ML Model Development" # Technical Capabilities capabilities: ["data-analysis", "visualization", "machine-learning"] coding_languages: ["python", "sql", "r"] frameworks: ["pandas", "numpy", "scikit-learn", "tensorflow"] tools: ["jupyter", "git", "docker"] technologies: ["machine-learning", "data-engineering"] # Domain Expertise industries: ["finance", "healthcare"] skills: ["statistical-analysis", "predictive-modeling"] domains: ["statistics", "mathematics"] languages: ["en", "es"] # Model Configuration model_requirements: min_context: 8192 preferred_models: ["claude-3-sonnet", "gpt-4"] temperature: 0.1 parameters: max_iterations: 5 confidence_threshold: 0.8 # Authorship author: "Nik Brazley" organization: "DataCorp" email: "data@example.com" license: "MIT" created: "2024-01-15T10:30:00Z" updated: "2024-06-22T14:20:00Z" # Discovery tags: ["python", "data-science", "ml"] category: "Data & Analytics" subcategory: "Machine Learning" use_cases: ["data-analysis", "predictive-modeling"] difficulty: "intermediate" # Dependencies dependencies: ["python>=3.8", "pandas"] integrations: ["jupyter", "vscode"] requires_internet: true --- ``` -------------------------------- ### Agent File YAML Frontmatter Schema Source: https://github.com/agentbrazley/dot.agent/blob/main/docs/schema.md Defines the complete schema for the YAML frontmatter in `.agent` files, detailing required, recommended, and optional fields with their types, descriptions, constraints, and examples. ```APIDOC name (string) [Required] Description: The unique identifier for the agent. Constraints: Must be a non-empty string. Should be descriptive and unique. Example: "DataAnalysisAgent" version (string) [Recommended] Description: Semantic version of the agent. Constraints: Must follow semantic versioning format (e.g., "1.0.0", "2.1.0-beta"). Used for version compatibility and updates. Example: "1.2.3" description (string) [Recommended] Description: Brief description of the agent's purpose. Constraints: Should be a single line summary. Maximum 200 characters recommended. Example: "Analyzes data patterns and generates insights" author (string) [Recommended] Description: Name of the agent's creator. Constraints: Can include email in format "Name ". Example: "Nik Brazley" or "Nik Brazley " homepage (string) [Optional] Description: URL to the agent's homepage or documentation. Constraints: Must be a valid URL. Example: "https://github.com/nikbrazley/myagent" repository (string) [Optional] Description: URL to the source code repository. Constraints: Must be a valid URL. Example: "https://github.com/nikbrazley/myagent" license (string) [Optional] Description: SPDX license identifier or custom license. Constraints: Prefer standard SPDX identifiers. Example: "MIT", "Apache-2.0", "GPL-3.0" tags (array of strings) [Optional] Description: Categorization tags for the agent. Constraints: Each tag should be lowercase. Use hyphens for multi-word tags. Example: ["data-analysis", "nlp", "automation"] capabilities (array of strings) [Optional] Description: List of agent capabilities. Constraints: Describe what the agent can do. Use consistent naming conventions. Example: - text-generation - code-analysis - data-visualization dependencies (object) [Optional] Description: External dependencies required by the agent. Constraints: Key: dependency name, Value: version specification. Example: openai: "^1.0.0" pandas: ">=2.0.0" numpy: "*" created (string) [Optional] Description: ISO 8601 timestamp of creation. Constraints: Format: YYYY-MM-DDTHH:mm:ssZ. Example: "2025-06-22T10:30:00Z" updated (string) [Optional] Description: ISO 8601 timestamp of last update. Constraints: Format: YYYY-MM-DDTHH:mm:ssZ. Example: "2025-06-22T15:45:00Z" deprecated (boolean) [Optional] Description: Indicates if the agent is deprecated. Default: false Example: true parameters (object) [Optional] Description: Configuration parameters for the agent. Constraints: Flexible object structure. Example: temperature: 0.7 max_tokens: 1000 model: gpt-4 examples (array of objects) [Optional] Description: Usage examples for the agent. Constraints: Each example should have input and output. Example: - input: "Analyze sales data for Q1" output: "Sales increased by 15%..." interfaces (array of strings) [Optional] Description: Supported interfaces or protocols. Example: ["rest-api", "cli", "websocket"] platforms (array of strings) [Optional] Description: Supported platforms. Example: ["windows", "macos", "linux", "web"] requirements (object) [Optional] Description: System requirements. Example: python: ">=3.8" memory: "4GB" gpu: false environment (object) [Optional] Description: Environment variables used by the agent. Constraints: Key: variable name, Value: description or default. Example: API_KEY: "OpenAI API key" DEBUG: "false" configuration (object) [Optional] Description: Agent-specific configuration. Constraints: Flexible structure based on agent needs. Example: timeout: 30 retries: 3 cache_enabled: true metrics (object) [Optional] Description: Performance or quality metrics. Example: accuracy: 0.95 response_time: "< 2s" tokens_per_second: 50 changelog (string or array) [Optional] Description: Recent changes or version history. Constraints: Can be a string or array of entries. Example: - "1.2.0: Added streaming support" - "1.1.0: Improved error handling" keywords (array of strings) [Optional] Description: SEO/search keywords. Constraints: Similar to tags but for discovery. Example: ["ai", "assistant", "chatbot"] ``` -------------------------------- ### Launch Agent App for Initial Registration Source: https://github.com/agentbrazley/dot.agent/blob/main/docs/macos-file-type-registration.md This command launches the `AgentFileType.app` application. Launching the app once is crucial as it triggers macOS's Launch Services to process the application's `Info.plist` and register the declared `.agent` file type with the system. ```bash open AgentFileType.app ``` -------------------------------- ### Run Agent App Creation Script Source: https://github.com/agentbrazley/dot.agent/blob/main/docs/macos-file-type-registration.md This bash command executes the script responsible for creating the `AgentFileType.app` bundle, which is essential for registering the `.agent` file type on macOS. It sets up the necessary application structure for file type declaration. ```bash ./macos-registration/create-agent-app.sh ``` -------------------------------- ### Agent File Validation Commands Source: https://github.com/agentbrazley/dot.agent/blob/main/RELEASE_NOTES.md Examples of using the agent-validator CLI to validate single .agent files, entire directories, and to lint and fix issues within agent definitions. ```bash # Validate a single file agent-validator validate myagent.agent # Validate all agents in a directory agent-validator validate ./agents # Lint and fix issues agent-validator lint --fix myagent.agent ``` -------------------------------- ### Verify .agent File UTI Recognition Source: https://github.com/agentbrazley/dot.agent/blob/main/docs/macos-file-type-registration.md This command uses `mdls` (metadata list) to check the Uniform Type Identifier (UTI) of an `example.agent` file. It specifically queries for `kMDItemContentType` to confirm that macOS correctly recognizes the file as `com.nikbrazley.agent` after registration. ```bash mdls -name kMDItemContentType example.agent ``` -------------------------------- ### Restart Finder Application Source: https://github.com/agentbrazley/dot.agent/blob/main/docs/macos-file-type-registration.md This command terminates the Finder application, which macOS automatically relaunches. Restarting Finder can help resolve issues where file type icons or Quick Look previews are not updating correctly in the Finder interface after registration. ```bash killall Finder ``` -------------------------------- ### Copy Agent App to Applications Directory Source: https://github.com/agentbrazley/dot.agent/blob/main/docs/macos-file-type-registration.md This command copies the `AgentFileType.app` bundle to the `/Applications` directory. This optional step ensures that the file type registration persists and the application is available in a standard location, making it less likely to be accidentally deleted. ```bash cp -r AgentFileType.app /Applications/ ``` -------------------------------- ### Reset Quick Look Caches Source: https://github.com/agentbrazley/dot.agent/blob/main/docs/macos-file-type-registration.md These commands are used to reset Quick Look's internal caches. `qlmanage -r cache` clears the cache, and `qlmanage -r` reloads Quick Look plugins, which can resolve issues where Quick Look previews are not appearing correctly for `.agent` files. ```bash qlmanage -r cache qlmanage -r ``` -------------------------------- ### Force Launch Services Refresh for Agent App Source: https://github.com/agentbrazley/dot.agent/blob/main/docs/macos-file-type-registration.md This command forces macOS's Launch Services to re-register or refresh its understanding of the `AgentFileType.app`. This is particularly useful if changes were made to the app's `Info.plist` or if the file type registration isn't immediately taking effect. ```bash /System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -f AgentFileType.app ``` -------------------------------- ### Re-register Agent App with Launch Services Source: https://github.com/agentbrazley/dot.agent/blob/main/docs/macos-file-type-registration.md This command explicitly re-registers the `AgentFileType.app` with macOS's Launch Services. It's a crucial troubleshooting step to ensure that the system re-processes the application's file type declarations, especially if previous attempts at registration were unsuccessful. ```bash /System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -f AgentFileType.app ``` -------------------------------- ### AgentSearchEngine Class API Reference Source: https://github.com/agentbrazley/dot.agent/blob/main/README.md The `AgentSearchEngine` class manages an index of agents, allowing for their addition, searching based on various criteria, and retrieval of recommendations. It provides methods to query agents by capabilities, languages, categories, and to generate use-case specific recommendations. ```APIDOC AgentSearchEngine: addAgent(agentId: string, metadata: AgentMetadata): void agentId: string - The unique identifier for the agent. metadata: AgentMetadata - The metadata object of the agent to add to the search index. Returns: void search(options: SearchOptions): SearchResult options: SearchOptions - An object containing search parameters like keywords, filters, and pagination. Returns: SearchResult - An object containing matching agents and search metadata. findByCapability(capability: string): AgentMetadata[] capability: string - The specific capability to search for (e.g., 'data-analysis'). Returns: AgentMetadata[] - An array of agent metadata objects that possess the specified capability. findByLanguage(language: string): AgentMetadata[] language: string - The language to search for (e.g., 'python'). Returns: AgentMetadata[] - An array of agent metadata objects that support the specified language. findByCategory(category: string): AgentMetadata[] category: string - The category to search for (e.g., 'Data & Analytics'). Returns: AgentMetadata[] - An array of agent metadata objects belonging to the specified category. getRecommendations(useCase: string, limit?: number): AgentMetadata[] useCase: string - A description of the use case for which recommendations are needed. limit?: number - Optional maximum number of recommendations to return. Returns: AgentMetadata[] - An array of recommended agent metadata objects. ``` -------------------------------- ### Instantiate and Use Data Analysis Agent in Python Source: https://github.com/agentbrazley/dot.agent/blob/main/docs/schema.md This Python code demonstrates how to import and instantiate the `DataAnalysisAgent` class, then call its `analyze` method with sample data. It shows the basic programmatic interaction with the agent. ```python from agents import DataAnalysisAgent agent = DataAnalysisAgent() results = agent.analyze(data) ``` -------------------------------- ### Register .agent File Type on macOS Source: https://github.com/agentbrazley/dot.agent/blob/main/README.md Steps to register `.agent` files as a recognized file type on macOS, enabling native support and Quick Look previews. This involves navigating to the project directory and executing a provided registration script. ```bash cd path/to/dot.agent ./macos-registration/create-agent-app.sh open AgentFileType.app ``` -------------------------------- ### Parse and Search Agent Files with agent-frontmatter Library Source: https://github.com/agentbrazley/dot.agent/blob/main/README.md TypeScript code illustrating how to use the `AgentParser` to read and validate an agent file, and the `AgentSearchEngine` to add agent metadata and perform searches based on queries and filters like coding languages and capabilities. ```typescript import { AgentParser, AgentSearchEngine } from 'agent-frontmatter'; // Parse and validate an agent file const content = await fs.readFile('my-agent.md', 'utf-8'); const { agentFile, validation } = AgentParser.parseAndValidate(content); if (validation.valid) { console.log('Agent:', agentFile.metadata.name); } else { console.error('Validation errors:', validation.errors); } // Search for agents const searchEngine = new AgentSearchEngine(); searchEngine.addAgent('agent-1', agentFile.metadata); const results = searchEngine.search({ query: 'python data', filters: { coding_languages: ['python'], capabilities: ['data-analysis'] } }); ``` -------------------------------- ### VersionManager Class API Reference Source: https://github.com/agentbrazley/dot.agent/blob/main/README.md The `VersionManager` class offers static utilities for managing version compatibility and suggesting version updates. It can check if a provided version is compatible with a required version, assess model compatibility for an agent based on context size, and recommend semantic version bumps based on the nature of changes. ```APIDOC VersionManager: static checkCompatibility(requiredVersion: string, providedVersion: string): VersionCompatibility requiredVersion: string - The minimum or exact version required. providedVersion: string - The version that is currently available or provided. Returns: VersionCompatibility - An enum or object indicating the compatibility status. static checkModelCompatibility(agent: AgentMetadata, model: string, contextSize: number): { compatible: boolean; issues: string[]; } agent: AgentMetadata - The metadata of the agent to check. model: string - The name of the model to check compatibility against. contextSize: number - The context size available for the model. Returns: { compatible: boolean; issues: string[]; } - An object indicating if the model is compatible and any issues found. static suggestVersionBump(currentVersion: string, changes: { breakingChanges?: boolean; newFeatures?: boolean; bugFixes?: boolean; }): VersionUpdate currentVersion: string - The current semantic version string (e.g., '1.0.0'). changes: { breakingChanges?: boolean; newFeatures?: boolean; bugFixes?: boolean; } - An object describing the types of changes made. Returns: VersionUpdate - An object suggesting the next semantic version based on the changes. ``` -------------------------------- ### Verify macOS .agent File Type Registration Source: https://github.com/agentbrazley/dot.agent/blob/main/README.md Commands to confirm the successful registration of the `.agent` file type on macOS. This includes checking the file's content type using `mdls` and verifying Quick Look functionality in Finder. ```bash mdls -name kMDItemContentType test.agent # Should output: com.nikbrazley.agent # Test Quick Look # Select any .agent file in Finder and press Space ``` -------------------------------- ### AgentParser Class API Reference Source: https://github.com/agentbrazley/dot.agent/blob/main/README.md The `AgentParser` class provides static methods for handling agent file content. It supports parsing YAML content into an `AgentFile` object, validating the parsed metadata, and serializing an `AgentFile` object back into YAML frontmatter. It also offers a combined parse and validate operation. ```APIDOC AgentParser: static parse(content: string, filePath?: string): AgentFile content: string - The string content of the agent file to parse. filePath?: string - Optional path to the file, used for context or error reporting. Returns: AgentFile - The parsed agent file object. static validate(agentFile: AgentFile): ValidationResult agentFile: AgentFile - The agent file object to validate. Returns: ValidationResult - An object indicating validation success or failure with issues. static parseAndValidate(content: string, filePath?: string): { agentFile: AgentFile; validation: ValidationResult; } content: string - The string content of the agent file to parse and validate. filePath?: string - Optional path to the file. Returns: { agentFile: AgentFile; validation: ValidationResult; } - An object containing both the parsed agent file and its validation result. static serialize(agentFile: AgentFile): string agentFile: AgentFile - The agent file object to serialize. Returns: string - The YAML frontmatter string representation of the agent file. ``` -------------------------------- ### .agent File Schema Definition Source: https://github.com/agentbrazley/dot.agent/blob/main/RELEASE_NOTES.md Defines the structure and fields available within the .agent file's YAML frontmatter, categorizing them by requirement level (Required, Recommended, Optional) with brief descriptions. ```APIDOC .agent File Schema: Required Fields: name: string description: Unique identifier for the agent Recommended Fields: version: string description: Semantic version (e.g., "1.0.0") description: string description: Brief description of the agent's purpose author: string description: Creator's name Optional Fields: capabilities: string[] description: Array of agent capabilities dependencies: string[] description: Other agents or systems required tags: string[] description: Categorization tags created: string (ISO 8601) description: ISO 8601 timestamp for creation updated: string (ISO 8601) description: ISO 8601 timestamp for last update homepage: string (URL) description: Project or documentation URL ...and many more ``` -------------------------------- ### Standard File Extension for Agent Files Source: https://github.com/agentbrazley/dot.agent/blob/main/docs/schema.md This snippet defines the mandatory file extension for all agent files, which is `.agent`. This convention helps in identifying agent configuration files. ```text .agent ``` -------------------------------- ### Official IANA Media Type for Agent Files Source: https://github.com/agentbrazley/dot.agent/blob/main/docs/schema.md This snippet specifies the official IANA media type for agent files, `application/vnd.agent+yaml`. This standard ensures proper identification and handling of `.agent` files across systems. ```text application/vnd.agent+yaml ``` -------------------------------- ### Define Data Analysis Agent Metadata Source: https://github.com/agentbrazley/dot.agent/blob/main/docs/schema.md This YAML snippet defines the complete metadata for the Data Analysis Agent, including its name, version, description, author, dependencies, capabilities, and system requirements. It serves as the primary configuration file for the agent. ```yaml --- name: DataAnalysisAgent version: 2.1.0 description: Advanced data analysis agent with ML capabilities author: Nik Brazley homepage: https://github.com/nikbrazley/data-agent repository: https://github.com/nikbrazley/data-agent license: MIT created: 2025-01-15T10:00:00Z updated: 2025-06-22T16:00:00Z tags: - data-analysis - machine-learning - visualization capabilities: - statistical-analysis - predictive-modeling - data-visualization - report-generation dependencies: pandas: "^2.0.0" scikit-learn: "^1.3.0" matplotlib: "^3.7.0" parameters: default_model: "random_forest" confidence_threshold: 0.95 interfaces: - rest-api - python-sdk - cli platforms: - linux - macos - windows requirements: python: ">=3.8" memory: "8GB" storage: "10GB" --- ``` -------------------------------- ### Validate Agent File using CLI Tool Source: https://github.com/agentbrazley/dot.agent/blob/main/docs/schema.md This Bash command illustrates how to use the `agent-validator` command-line interface tool to validate an agent definition file. It ensures the file adheres to the specified schema and standards. ```bash agent-validator validate myagent.agent ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.