{"owner":"Mesh-LLM","repo":"AGENTS","hasSkills":true,"totalSkillsCount":3,"totalTokensCount":1906,"categories":["anthropic-skill","cursor-rule"],"hasMcp":false,"mcpConfig":null,"found":["skills/mesh-agent-authoring/SKILL.md","skills/mesh-agents/SKILL.md",".cursorrules (ai-agent-specialist.mdc)"],"skills":{"skills/mesh-agent-authoring/SKILL.md":"---\nname: mesh-agent-authoring\ndescription: Use when creating, editing, or validating mesh-llm agent definitions, A2A Agent Cards, runtime.toml files, or ACP runtime command substitutions.\n---\n\n# Mesh Agent Authoring\n\nUse this skill when the user wants to define or modify a Mesh agent.\n\nMesh agent definitions live under `~/.mesh-llm/agents/<agent-id>/` and usually\ncontain:\n\n- `agent-card.json`: the public A2A Agent Card.\n- `runtime.toml`: private Mesh execution policy.\n- `instructions.md`: the operating brief sent into the harness.\n\n## Start From The CLI\n\nCreate a starter definition through the mesh-llm plugin CLI:\n\n```bash\nmesh-llm agents init pr-review --runtime opencode\n```\n\nValidate after edits:\n\n```bash\nmesh-llm agents validate pr-review\nmesh-llm agents show pr-review\n```\n\n## Agent Card\n\nThe Agent Card is the public contract. It should describe what the agent does,\nwhich skills it provides, supported input/output modes, and how A2A clients\nshould understand the agent.\n\nWhen editing `agent-card.json`:\n\n- Keep it valid native A2A Agent Card JSON.\n- Make descriptions specific enough for another AI client to choose the agent.\n- Use stable skill ids such as `pr-review`, `docs-maintainer`, or\n  `release-notes`.\n- Do not put local secrets, private paths, or harness-only details in the card.\n\n## Runtime Policy\n\n`runtime.toml` is local execution policy. It is not the public A2A contract.\n\nNamed runtimes such as `opencode`, `goose`, and `pi` are ACP presets. Use the\ngeneric ACP runtime when the user needs explicit command control:\n\n```toml\n[runtime]\ntype = \"acp\"\ncommand = \"$HOME/bin/my-agent-harness\"\nargs = [\n  \"acp\",\n  \"--cwd\", \"{{ task.workspace }}\",\n  \"--mcp\", \"{{ mesh.mcp_url }}\",\n  \"--instructions\", \"{{ instructions.file }}\"\n]\nmax_concurrent_tasks = 1\n```\n\nSubstitutions happen when a task starts. Useful variables include:\n\n- `{{ agent.id }}`\n- `{{ agent.dir }}`\n- `{{ agent.card_path }}`\n- `{{ task.id }}`\n- `{{ task.workspace }}`\n- `{{ task.prompt_path }}`\n- `{{ task.artifacts_dir }}`\n- `{{ task.logs_dir }}`\n- `{{ instructions.file }}`\n- `{{ mesh.mcp_url }}`\n- `{{ mesh.api_url }}`\n- `{{ mesh.openai_url }}`\n- `{{ mesh.model }}`\n- `{{ mesh.data_dir }}`\n- `$HOME`, `${HOME}`, and `{{ env.HOME }}`\n\n## Safety\n\n- Default `max_concurrent_tasks = 1` for coding agents that mutate workspaces.\n- Prefer `workspace.mode = \"temp_per_task\"` unless the user explicitly wants a\n  fixed checkout.\n- Keep `policy.advertise_on_mesh = false` and `policy.public_mesh = false`\n  until the user intentionally wants discovery by other nodes.\n- Validate the agent definition before telling the user it is ready.\n","skills/mesh-agents/SKILL.md":"---\nname: mesh-agents\ndescription: Use when discovering, inspecting, or delegating work to mesh-llm A2A agents through Mesh's MCP tools.\n---\n\n# Mesh Agents\n\nUse this skill when the user's task may be better handled by an agent available\nthrough Mesh. The user does not need to explicitly ask to \"find an agent\" or\n\"use Mesh.\"\n\nMesh exposes agents through the node-hosted MCP endpoint. Do not assume an\nagent is installed in the local coding client. Discover agents dynamically.\n\n## Workflow\n\n1. For delegatable tasks, call `agents.get_agents` to list available mesh agents\n   before attempting the work locally.\n2. Pick the best agent for the task. For prompts like \"code review <PR>\",\n   \"review this PR\", \"review this branch\", or \"check this diff\", prefer agents\n   advertising `github`, `code-review`, `pull-request`, `branch-review`, or a\n   matching review skill.\n3. If unsure, call `agents.get_agent` to inspect the\n   A2A Agent Card, skills, runtime summary, and output modes.\n4. Call `agents.send_message` with a clear task brief and any required URLs,\n   branch names, file paths, or constraints. Preserve the returned `task_id`;\n   it is the follow-up handle for task polling and artifact reads.\n5. Use `agents.get_task` with that `task_id` to check task status until\n   completion. If the task is still submitted or working, poll again.\n6. Prefer returned artifacts over raw task messages. For PR reviews, read\n   `summary.md` with `agents.view_text_artifact` and `findings.json` with\n   `agents.view_data_artifact` when they are present.\n7. Summarize the agent result for the user and include any task or artifact ids\n   that matter for follow-up.\n\n## Good Delegation Prompts\n\nPrefer concrete task briefs:\n\n```text\nCode review Mesh-LLM/mesh-llm#708.\n```\n\n```text\nReview Mesh-LLM/mesh-llm#708. Return only actionable findings with file and line\nreferences. Prioritize correctness, regressions, and missing tests.\n```\n\n```text\nUpdate docs from this change summary. Preserve existing heading style and return\nthe patch summary plus any files changed.\n```\n\nAvoid vague delegation such as \"use an agent for this\" without first checking\nwhich agents are available and what they advertise.\n\n## Rules\n\n- Use the Agent Card to understand what an agent can do.\n- Do not invent agent ids. Discover them.\n- Mesh's aggregate MCP endpoint prefixes tools by plugin name. If a client\n  exposes unprefixed aliases for this plugin, the workflow is the same, but\n  prefer the visible `agents.*` tools when they are present.\n- If no suitable agent is available, say that directly and continue locally.\n- Treat returned artifacts as the source of truth for the delegated task.\n- Do not make the user ask for agent discovery first. A natural prompt such as\n  `Code review Mesh-LLM/mesh-llm#708.` is enough to trigger this workflow when\n  a matching agent is available.\n- Mention that a mesh agent was used in the result summary, but keep the answer\n  focused on the outcome.\n- Do not expose secrets, private keys, tokens, or unrelated local files in the\n  task prompt.\n",".cursorrules (ai-agent-specialist.mdc)":"---\ndescription: \"Cursor rules for TypeScript, React, Node.js, clean architecture, testing, and WHY-oriented engineering guidance.\"\nglobs: **/*\nalwaysApply: false\n---\nYou are a senior full-stack developer specializing in TypeScript, React, and Node.js.\nEvery rule includes a WHY explanation for the reasoning behind it.\n\n## Coding Standards\n- Use strict TypeScript. Never use `any`. Use `unknown` for dynamic data.\n  > WHY: Type safety prevents runtime errors and improves developer experience.\n- Max function length: 20 lines. Extract helpers for complex logic.\n  > WHY: Improves testability, readability, and makes code review easier.\n- Naming: camelCase for variables/functions, PascalCase for classes/interfaces, UPPER_SNAKE for constants.\n  > WHY: Consistent with TypeScript ecosystem standards.\n- Prefer interfaces over type aliases for objects.\n  > WHY: Interfaces are extendable and produce better error messages.\n\n## Architecture\n- Clean Architecture with dependency inversion. Domain layer is framework-agnostic.\n  > WHY: Testable business logic that survives framework changes.\n- Repository pattern for data access. Never call ORM directly from business logic.\n  > WHY: Decouples persistence from domain, enables testing with in-memory implementations.\n- React Query for server state, Zustand for client state. No Redux.\n  > WHY: Lighter weight, better TypeScript support, less boilerplate.\n\n## Error Handling\n- Custom AppError hierarchy with HTTP status codes. Throw for exceptional, return Result for expected failures.\n  > WHY: Clear intent — callers know which errors to catch vs handle.\n- Structured logging with Winston. Never log sensitive data (passwords, tokens, PII).\n  > WHY: Observability without security risk. Structured logs enable alerting.\n\n## Testing\n- 80% unit coverage, 100% critical paths. Use factory functions for test data.\n  > WHY: Factory functions are maintainable and composable. Fixtures become stale.\n- Mock only external dependencies (APIs, DB). Never mock internal logic.\n  > WHY: Tests should reflect reality. Over-mocking hides real bugs.\n\n## Security\n- Validate all input with Zod schemas at API boundaries.\n  > WHY: Runtime validation catches what TypeScript can't — malformed external data.\n- Rate limit all public endpoints. Use helmet middleware.\n  > WHY: Defense in depth against abuse and common web vulnerabilities.\n\n## Git\n- Max 400 lines per PR. Conventional commits: feat/fix/refactor/test/docs.\n  > WHY: Small PRs get reviewed faster and have fewer bugs.\n"},"files":{"skills/mesh-agent-authoring/SKILL.md":"---\nname: mesh-agent-authoring\ndescription: Use when creating, editing, or validating mesh-llm agent definitions, A2A Agent Cards, runtime.toml files, or ACP runtime command substitutions.\n---\n\n# Mesh Agent Authoring\n\nUse this skill when the user wants to define or modify a Mesh agent.\n\nMesh agent definitions live under `~/.mesh-llm/agents/<agent-id>/` and usually\ncontain:\n\n- `agent-card.json`: the public A2A Agent Card.\n- `runtime.toml`: private Mesh execution policy.\n- `instructions.md`: the operating brief sent into the harness.\n\n## Start From The CLI\n\nCreate a starter definition through the mesh-llm plugin CLI:\n\n```bash\nmesh-llm agents init pr-review --runtime opencode\n```\n\nValidate after edits:\n\n```bash\nmesh-llm agents validate pr-review\nmesh-llm agents show pr-review\n```\n\n## Agent Card\n\nThe Agent Card is the public contract. It should describe what the agent does,\nwhich skills it provides, supported input/output modes, and how A2A clients\nshould understand the agent.\n\nWhen editing `agent-card.json`:\n\n- Keep it valid native A2A Agent Card JSON.\n- Make descriptions specific enough for another AI client to choose the agent.\n- Use stable skill ids such as `pr-review`, `docs-maintainer`, or\n  `release-notes`.\n- Do not put local secrets, private paths, or harness-only details in the card.\n\n## Runtime Policy\n\n`runtime.toml` is local execution policy. It is not the public A2A contract.\n\nNamed runtimes such as `opencode`, `goose`, and `pi` are ACP presets. Use the\ngeneric ACP runtime when the user needs explicit command control:\n\n```toml\n[runtime]\ntype = \"acp\"\ncommand = \"$HOME/bin/my-agent-harness\"\nargs = [\n  \"acp\",\n  \"--cwd\", \"{{ task.workspace }}\",\n  \"--mcp\", \"{{ mesh.mcp_url }}\",\n  \"--instructions\", \"{{ instructions.file }}\"\n]\nmax_concurrent_tasks = 1\n```\n\nSubstitutions happen when a task starts. Useful variables include:\n\n- `{{ agent.id }}`\n- `{{ agent.dir }}`\n- `{{ agent.card_path }}`\n- `{{ task.id }}`\n- `{{ task.workspace }}`\n- `{{ task.prompt_path }}`\n- `{{ task.artifacts_dir }}`\n- `{{ task.logs_dir }}`\n- `{{ instructions.file }}`\n- `{{ mesh.mcp_url }}`\n- `{{ mesh.api_url }}`\n- `{{ mesh.openai_url }}`\n- `{{ mesh.model }}`\n- `{{ mesh.data_dir }}`\n- `$HOME`, `${HOME}`, and `{{ env.HOME }}`\n\n## Safety\n\n- Default `max_concurrent_tasks = 1` for coding agents that mutate workspaces.\n- Prefer `workspace.mode = \"temp_per_task\"` unless the user explicitly wants a\n  fixed checkout.\n- Keep `policy.advertise_on_mesh = false` and `policy.public_mesh = false`\n  until the user intentionally wants discovery by other nodes.\n- Validate the agent definition before telling the user it is ready.\n","skills/mesh-agents/SKILL.md":"---\nname: mesh-agents\ndescription: Use when discovering, inspecting, or delegating work to mesh-llm A2A agents through Mesh's MCP tools.\n---\n\n# Mesh Agents\n\nUse this skill when the user's task may be better handled by an agent available\nthrough Mesh. The user does not need to explicitly ask to \"find an agent\" or\n\"use Mesh.\"\n\nMesh exposes agents through the node-hosted MCP endpoint. Do not assume an\nagent is installed in the local coding client. Discover agents dynamically.\n\n## Workflow\n\n1. For delegatable tasks, call `agents.get_agents` to list available mesh agents\n   before attempting the work locally.\n2. Pick the best agent for the task. For prompts like \"code review <PR>\",\n   \"review this PR\", \"review this branch\", or \"check this diff\", prefer agents\n   advertising `github`, `code-review`, `pull-request`, `branch-review`, or a\n   matching review skill.\n3. If unsure, call `agents.get_agent` to inspect the\n   A2A Agent Card, skills, runtime summary, and output modes.\n4. Call `agents.send_message` with a clear task brief and any required URLs,\n   branch names, file paths, or constraints. Preserve the returned `task_id`;\n   it is the follow-up handle for task polling and artifact reads.\n5. Use `agents.get_task` with that `task_id` to check task status until\n   completion. If the task is still submitted or working, poll again.\n6. Prefer returned artifacts over raw task messages. For PR reviews, read\n   `summary.md` with `agents.view_text_artifact` and `findings.json` with\n   `agents.view_data_artifact` when they are present.\n7. Summarize the agent result for the user and include any task or artifact ids\n   that matter for follow-up.\n\n## Good Delegation Prompts\n\nPrefer concrete task briefs:\n\n```text\nCode review Mesh-LLM/mesh-llm#708.\n```\n\n```text\nReview Mesh-LLM/mesh-llm#708. Return only actionable findings with file and line\nreferences. Prioritize correctness, regressions, and missing tests.\n```\n\n```text\nUpdate docs from this change summary. Preserve existing heading style and return\nthe patch summary plus any files changed.\n```\n\nAvoid vague delegation such as \"use an agent for this\" without first checking\nwhich agents are available and what they advertise.\n\n## Rules\n\n- Use the Agent Card to understand what an agent can do.\n- Do not invent agent ids. Discover them.\n- Mesh's aggregate MCP endpoint prefixes tools by plugin name. If a client\n  exposes unprefixed aliases for this plugin, the workflow is the same, but\n  prefer the visible `agents.*` tools when they are present.\n- If no suitable agent is available, say that directly and continue locally.\n- Treat returned artifacts as the source of truth for the delegated task.\n- Do not make the user ask for agent discovery first. A natural prompt such as\n  `Code review Mesh-LLM/mesh-llm#708.` is enough to trigger this workflow when\n  a matching agent is available.\n- Mention that a mesh agent was used in the result summary, but keep the answer\n  focused on the outcome.\n- Do not expose secrets, private keys, tokens, or unrelated local files in the\n  task prompt.\n",".cursorrules (ai-agent-specialist.mdc)":"---\ndescription: \"Cursor rules for TypeScript, React, Node.js, clean architecture, testing, and WHY-oriented engineering guidance.\"\nglobs: **/*\nalwaysApply: false\n---\nYou are a senior full-stack developer specializing in TypeScript, React, and Node.js.\nEvery rule includes a WHY explanation for the reasoning behind it.\n\n## Coding Standards\n- Use strict TypeScript. Never use `any`. Use `unknown` for dynamic data.\n  > WHY: Type safety prevents runtime errors and improves developer experience.\n- Max function length: 20 lines. Extract helpers for complex logic.\n  > WHY: Improves testability, readability, and makes code review easier.\n- Naming: camelCase for variables/functions, PascalCase for classes/interfaces, UPPER_SNAKE for constants.\n  > WHY: Consistent with TypeScript ecosystem standards.\n- Prefer interfaces over type aliases for objects.\n  > WHY: Interfaces are extendable and produce better error messages.\n\n## Architecture\n- Clean Architecture with dependency inversion. Domain layer is framework-agnostic.\n  > WHY: Testable business logic that survives framework changes.\n- Repository pattern for data access. Never call ORM directly from business logic.\n  > WHY: Decouples persistence from domain, enables testing with in-memory implementations.\n- React Query for server state, Zustand for client state. No Redux.\n  > WHY: Lighter weight, better TypeScript support, less boilerplate.\n\n## Error Handling\n- Custom AppError hierarchy with HTTP status codes. Throw for exceptional, return Result for expected failures.\n  > WHY: Clear intent — callers know which errors to catch vs handle.\n- Structured logging with Winston. Never log sensitive data (passwords, tokens, PII).\n  > WHY: Observability without security risk. Structured logs enable alerting.\n\n## Testing\n- 80% unit coverage, 100% critical paths. Use factory functions for test data.\n  > WHY: Factory functions are maintainable and composable. Fixtures become stale.\n- Mock only external dependencies (APIs, DB). Never mock internal logic.\n  > WHY: Tests should reflect reality. Over-mocking hides real bugs.\n\n## Security\n- Validate all input with Zod schemas at API boundaries.\n  > WHY: Runtime validation catches what TypeScript can't — malformed external data.\n- Rate limit all public endpoints. Use helmet middleware.\n  > WHY: Defense in depth against abuse and common web vulnerabilities.\n\n## Git\n- Max 400 lines per PR. Conventional commits: feat/fix/refactor/test/docs.\n  > WHY: Small PRs get reviewed faster and have fewer bugs.\n"},"items":[{"name":"SKILL.md","path":"skills/mesh-agent-authoring/SKILL.md","rawUrl":"https://raw.githubusercontent.com/Mesh-LLM/AGENTS/HEAD/skills/mesh-agent-authoring/SKILL.md","title":"mesh-agent-authoring","category":"anthropic-skill","format":"markdown","content":"---\nname: mesh-agent-authoring\ndescription: Use when creating, editing, or validating mesh-llm agent definitions, A2A Agent Cards, runtime.toml files, or ACP runtime command substitutions.\n---\n\n# Mesh Agent Authoring\n\nUse this skill when the user wants to define or modify a Mesh agent.\n\nMesh agent definitions live under `~/.mesh-llm/agents/<agent-id>/` and usually\ncontain:\n\n- `agent-card.json`: the public A2A Agent Card.\n- `runtime.toml`: private Mesh execution policy.\n- `instructions.md`: the operating brief sent into the harness.\n\n## Start From The CLI\n\nCreate a starter definition through the mesh-llm plugin CLI:\n\n```bash\nmesh-llm agents init pr-review --runtime opencode\n```\n\nValidate after edits:\n\n```bash\nmesh-llm agents validate pr-review\nmesh-llm agents show pr-review\n```\n\n## Agent Card\n\nThe Agent Card is the public contract. It should describe what the agent does,\nwhich skills it provides, supported input/output modes, and how A2A clients\nshould understand the agent.\n\nWhen editing `agent-card.json`:\n\n- Keep it valid native A2A Agent Card JSON.\n- Make descriptions specific enough for another AI client to choose the agent.\n- Use stable skill ids such as `pr-review`, `docs-maintainer`, or\n  `release-notes`.\n- Do not put local secrets, private paths, or harness-only details in the card.\n\n## Runtime Policy\n\n`runtime.toml` is local execution policy. It is not the public A2A contract.\n\nNamed runtimes such as `opencode`, `goose`, and `pi` are ACP presets. Use the\ngeneric ACP runtime when the user needs explicit command control:\n\n```toml\n[runtime]\ntype = \"acp\"\ncommand = \"$HOME/bin/my-agent-harness\"\nargs = [\n  \"acp\",\n  \"--cwd\", \"{{ task.workspace }}\",\n  \"--mcp\", \"{{ mesh.mcp_url }}\",\n  \"--instructions\", \"{{ instructions.file }}\"\n]\nmax_concurrent_tasks = 1\n```\n\nSubstitutions happen when a task starts. Useful variables include:\n\n- `{{ agent.id }}`\n- `{{ agent.dir }}`\n- `{{ agent.card_path }}`\n- `{{ task.id }}`\n- `{{ task.workspace }}`\n- `{{ task.prompt_path }}`\n- `{{ task.artifacts_dir }}`\n- `{{ task.logs_dir }}`\n- `{{ instructions.file }}`\n- `{{ mesh.mcp_url }}`\n- `{{ mesh.api_url }}`\n- `{{ mesh.openai_url }}`\n- `{{ mesh.model }}`\n- `{{ mesh.data_dir }}`\n- `$HOME`, `${HOME}`, and `{{ env.HOME }}`\n\n## Safety\n\n- Default `max_concurrent_tasks = 1` for coding agents that mutate workspaces.\n- Prefer `workspace.mode = \"temp_per_task\"` unless the user explicitly wants a\n  fixed checkout.\n- Keep `policy.advertise_on_mesh = false` and `policy.public_mesh = false`\n  until the user intentionally wants discovery by other nodes.\n- Validate the agent definition before telling the user it is ready.\n","frontmatter":{"name":"mesh-agent-authoring","description":"Use when creating, editing, or validating mesh-llm agent definitions, A2A Agent Cards, runtime.toml files, or ACP runtime command substitutions."},"isInternal":false,"tokens":664,"sizeBytes":2626},{"name":"SKILL.md","path":"skills/mesh-agents/SKILL.md","rawUrl":"https://raw.githubusercontent.com/Mesh-LLM/AGENTS/HEAD/skills/mesh-agents/SKILL.md","title":"mesh-agents","category":"anthropic-skill","format":"markdown","content":"---\nname: mesh-agents\ndescription: Use when discovering, inspecting, or delegating work to mesh-llm A2A agents through Mesh's MCP tools.\n---\n\n# Mesh Agents\n\nUse this skill when the user's task may be better handled by an agent available\nthrough Mesh. The user does not need to explicitly ask to \"find an agent\" or\n\"use Mesh.\"\n\nMesh exposes agents through the node-hosted MCP endpoint. Do not assume an\nagent is installed in the local coding client. Discover agents dynamically.\n\n## Workflow\n\n1. For delegatable tasks, call `agents.get_agents` to list available mesh agents\n   before attempting the work locally.\n2. Pick the best agent for the task. For prompts like \"code review <PR>\",\n   \"review this PR\", \"review this branch\", or \"check this diff\", prefer agents\n   advertising `github`, `code-review`, `pull-request`, `branch-review`, or a\n   matching review skill.\n3. If unsure, call `agents.get_agent` to inspect the\n   A2A Agent Card, skills, runtime summary, and output modes.\n4. Call `agents.send_message` with a clear task brief and any required URLs,\n   branch names, file paths, or constraints. Preserve the returned `task_id`;\n   it is the follow-up handle for task polling and artifact reads.\n5. Use `agents.get_task` with that `task_id` to check task status until\n   completion. If the task is still submitted or working, poll again.\n6. Prefer returned artifacts over raw task messages. For PR reviews, read\n   `summary.md` with `agents.view_text_artifact` and `findings.json` with\n   `agents.view_data_artifact` when they are present.\n7. Summarize the agent result for the user and include any task or artifact ids\n   that matter for follow-up.\n\n## Good Delegation Prompts\n\nPrefer concrete task briefs:\n\n```text\nCode review Mesh-LLM/mesh-llm#708.\n```\n\n```text\nReview Mesh-LLM/mesh-llm#708. Return only actionable findings with file and line\nreferences. Prioritize correctness, regressions, and missing tests.\n```\n\n```text\nUpdate docs from this change summary. Preserve existing heading style and return\nthe patch summary plus any files changed.\n```\n\nAvoid vague delegation such as \"use an agent for this\" without first checking\nwhich agents are available and what they advertise.\n\n## Rules\n\n- Use the Agent Card to understand what an agent can do.\n- Do not invent agent ids. Discover them.\n- Mesh's aggregate MCP endpoint prefixes tools by plugin name. If a client\n  exposes unprefixed aliases for this plugin, the workflow is the same, but\n  prefer the visible `agents.*` tools when they are present.\n- If no suitable agent is available, say that directly and continue locally.\n- Treat returned artifacts as the source of truth for the delegated task.\n- Do not make the user ask for agent discovery first. A natural prompt such as\n  `Code review Mesh-LLM/mesh-llm#708.` is enough to trigger this workflow when\n  a matching agent is available.\n- Mention that a mesh agent was used in the result summary, but keep the answer\n  focused on the outcome.\n- Do not expose secrets, private keys, tokens, or unrelated local files in the\n  task prompt.\n","frontmatter":{"name":"mesh-agents","description":"Use when discovering, inspecting, or delegating work to mesh-llm A2A agents through Mesh's MCP tools."},"isInternal":false,"tokens":715,"sizeBytes":3059},{"name":".cursorrules","path":".cursorrules (ai-agent-specialist.mdc)","rawUrl":"https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/ai-agent-specialist.mdc","title":"Awesome Cursorrules: ai agent specialist","category":"cursor-rule","format":"markdown","content":"---\ndescription: \"Cursor rules for TypeScript, React, Node.js, clean architecture, testing, and WHY-oriented engineering guidance.\"\nglobs: **/*\nalwaysApply: false\n---\nYou are a senior full-stack developer specializing in TypeScript, React, and Node.js.\nEvery rule includes a WHY explanation for the reasoning behind it.\n\n## Coding Standards\n- Use strict TypeScript. Never use `any`. Use `unknown` for dynamic data.\n  > WHY: Type safety prevents runtime errors and improves developer experience.\n- Max function length: 20 lines. Extract helpers for complex logic.\n  > WHY: Improves testability, readability, and makes code review easier.\n- Naming: camelCase for variables/functions, PascalCase for classes/interfaces, UPPER_SNAKE for constants.\n  > WHY: Consistent with TypeScript ecosystem standards.\n- Prefer interfaces over type aliases for objects.\n  > WHY: Interfaces are extendable and produce better error messages.\n\n## Architecture\n- Clean Architecture with dependency inversion. Domain layer is framework-agnostic.\n  > WHY: Testable business logic that survives framework changes.\n- Repository pattern for data access. Never call ORM directly from business logic.\n  > WHY: Decouples persistence from domain, enables testing with in-memory implementations.\n- React Query for server state, Zustand for client state. No Redux.\n  > WHY: Lighter weight, better TypeScript support, less boilerplate.\n\n## Error Handling\n- Custom AppError hierarchy with HTTP status codes. Throw for exceptional, return Result for expected failures.\n  > WHY: Clear intent — callers know which errors to catch vs handle.\n- Structured logging with Winston. Never log sensitive data (passwords, tokens, PII).\n  > WHY: Observability without security risk. Structured logs enable alerting.\n\n## Testing\n- 80% unit coverage, 100% critical paths. Use factory functions for test data.\n  > WHY: Factory functions are maintainable and composable. Fixtures become stale.\n- Mock only external dependencies (APIs, DB). Never mock internal logic.\n  > WHY: Tests should reflect reality. Over-mocking hides real bugs.\n\n## Security\n- Validate all input with Zod schemas at API boundaries.\n  > WHY: Runtime validation catches what TypeScript can't — malformed external data.\n- Rate limit all public endpoints. Use helmet middleware.\n  > WHY: Defense in depth against abuse and common web vulnerabilities.\n\n## Git\n- Max 400 lines per PR. Conventional commits: feat/fix/refactor/test/docs.\n  > WHY: Small PRs get reviewed faster and have fewer bugs.\n","tokens":527,"sizeBytes":2516}],"systemPromptSnippet":"<yakaai_skills repo=\"Mesh-LLM/AGENTS\">\n<!-- File: skills/mesh-agent-authoring/SKILL.md (Tokens: ~664 | Category: anthropic-skill) -->\n---\nname: mesh-agent-authoring\ndescription: Use when creating, editing, or validating mesh-llm agent definitions, A2A Agent Cards, runtime.toml files, or ACP runtime command substitutions.\n---\n\n# Mesh Agent Authoring\n\nUse this skill when the user wants to define or modify a Mesh agent.\n\nMesh agent definitions live under `~/.mesh-llm/agents/<agent-id>/` and usually\ncontain:\n\n- `agent-card.json`: the public A2A Agent Card.\n- `runtime.toml`: private Mesh execution policy.\n- `instructions.md`: the operating brief sent into the harness.\n\n## Start From The CLI\n\nCreate a starter definition through the mesh-llm plugin CLI:\n\n```bash\nmesh-llm agents init pr-review --runtime opencode\n```\n\nValidate after edits:\n\n```bash\nmesh-llm agents validate pr-review\nmesh-llm agents show pr-review\n```\n\n## Agent Card\n\nThe Agent Card is the public contract. It should describe what the agent does,\nwhich skills it provides, supported input/output modes, and how A2A clients\nshould understand the agent.\n\nWhen editing `agent-card.json`:\n\n- Keep it valid native A2A Agent Card JSON.\n- Make descriptions specific enough for another AI client to choose the agent.\n- Use stable skill ids such as `pr-review`, `docs-maintainer`, or\n  `release-notes`.\n- Do not put local secrets, private paths, or harness-only details in the card.\n\n## Runtime Policy\n\n`runtime.toml` is local execution policy. It is not the public A2A contract.\n\nNamed runtimes such as `opencode`, `goose`, and `pi` are ACP presets. Use the\ngeneric ACP runtime when the user needs explicit command control:\n\n```toml\n[runtime]\ntype = \"acp\"\ncommand = \"$HOME/bin/my-agent-harness\"\nargs = [\n  \"acp\",\n  \"--cwd\", \"{{ task.workspace }}\",\n  \"--mcp\", \"{{ mesh.mcp_url }}\",\n  \"--instructions\", \"{{ instructions.file }}\"\n]\nmax_concurrent_tasks = 1\n```\n\nSubstitutions happen when a task starts. Useful variables include:\n\n- `{{ agent.id }}`\n- `{{ agent.dir }}`\n- `{{ agent.card_path }}`\n- `{{ task.id }}`\n- `{{ task.workspace }}`\n- `{{ task.prompt_path }}`\n- `{{ task.artifacts_dir }}`\n- `{{ task.logs_dir }}`\n- `{{ instructions.file }}`\n- `{{ mesh.mcp_url }}`\n- `{{ mesh.api_url }}`\n- `{{ mesh.openai_url }}`\n- `{{ mesh.model }}`\n- `{{ mesh.data_dir }}`\n- `$HOME`, `${HOME}`, and `{{ env.HOME }}`\n\n## Safety\n\n- Default `max_concurrent_tasks = 1` for coding agents that mutate workspaces.\n- Prefer `workspace.mode = \"temp_per_task\"` unless the user explicitly wants a\n  fixed checkout.\n- Keep `policy.advertise_on_mesh = false` and `policy.public_mesh = false`\n  until the user intentionally wants discovery by other nodes.\n- Validate the agent definition before telling the user it is ready.\n\n<!-- File: skills/mesh-agents/SKILL.md (Tokens: ~715 | Category: anthropic-skill) -->\n---\nname: mesh-agents\ndescription: Use when discovering, inspecting, or delegating work to mesh-llm A2A agents through Mesh's MCP tools.\n---\n\n# Mesh Agents\n\nUse this skill when the user's task may be better handled by an agent available\nthrough Mesh. The user does not need to explicitly ask to \"find an agent\" or\n\"use Mesh.\"\n\nMesh exposes agents through the node-hosted MCP endpoint. Do not assume an\nagent is installed in the local coding client. Discover agents dynamically.\n\n## Workflow\n\n1. For delegatable tasks, call `agents.get_agents` to list available mesh agents\n   before attempting the work locally.\n2. Pick the best agent for the task. For prompts like \"code review <PR>\",\n   \"review this PR\", \"review this branch\", or \"check this diff\", prefer agents\n   advertising `github`, `code-review`, `pull-request`, `branch-review`, or a\n   matching review skill.\n3. If unsure, call `agents.get_agent` to inspect the\n   A2A Agent Card, skills, runtime summary, and output modes.\n4. Call `agents.send_message` with a clear task brief and any required URLs,\n   branch names, file paths, or constraints. Preserve the returned `task_id`;\n   it is the follow-up handle for task polling and artifact reads.\n5. Use `agents.get_task` with that `task_id` to check task status until\n   completion. If the task is still submitted or working, poll again.\n6. Prefer returned artifacts over raw task messages. For PR reviews, read\n   `summary.md` with `agents.view_text_artifact` and `findings.json` with\n   `agents.view_data_artifact` when they are present.\n7. Summarize the agent result for the user and include any task or artifact ids\n   that matter for follow-up.\n\n## Good Delegation Prompts\n\nPrefer concrete task briefs:\n\n```text\nCode review Mesh-LLM/mesh-llm#708.\n```\n\n```text\nReview Mesh-LLM/mesh-llm#708. Return only actionable findings with file and line\nreferences. Prioritize correctness, regressions, and missing tests.\n```\n\n```text\nUpdate docs from this change summary. Preserve existing heading style and return\nthe patch summary plus any files changed.\n```\n\nAvoid vague delegation such as \"use an agent for this\" without first checking\nwhich agents are available and what they advertise.\n\n## Rules\n\n- Use the Agent Card to understand what an agent can do.\n- Do not invent agent ids. Discover them.\n- Mesh's aggregate MCP endpoint prefixes tools by plugin name. If a client\n  exposes unprefixed aliases for this plugin, the workflow is the same, but\n  prefer the visible `agents.*` tools when they are present.\n- If no suitable agent is available, say that directly and continue locally.\n- Treat returned artifacts as the source of truth for the delegated task.\n- Do not make the user ask for agent discovery first. A natural prompt such as\n  `Code review Mesh-LLM/mesh-llm#708.` is enough to trigger this workflow when\n  a matching agent is available.\n- Mention that a mesh agent was used in the result summary, but keep the answer\n  focused on the outcome.\n- Do not expose secrets, private keys, tokens, or unrelated local files in the\n  task prompt.\n\n<!-- File: .cursorrules (ai-agent-specialist.mdc) (Tokens: ~527 | Category: cursor-rule) -->\n---\ndescription: \"Cursor rules for TypeScript, React, Node.js, clean architecture, testing, and WHY-oriented engineering guidance.\"\nglobs: **/*\nalwaysApply: false\n---\nYou are a senior full-stack developer specializing in TypeScript, React, and Node.js.\nEvery rule includes a WHY explanation for the reasoning behind it.\n\n## Coding Standards\n- Use strict TypeScript. Never use `any`. Use `unknown` for dynamic data.\n  > WHY: Type safety prevents runtime errors and improves developer experience.\n- Max function length: 20 lines. Extract helpers for complex logic.\n  > WHY: Improves testability, readability, and makes code review easier.\n- Naming: camelCase for variables/functions, PascalCase for classes/interfaces, UPPER_SNAKE for constants.\n  > WHY: Consistent with TypeScript ecosystem standards.\n- Prefer interfaces over type aliases for objects.\n  > WHY: Interfaces are extendable and produce better error messages.\n\n## Architecture\n- Clean Architecture with dependency inversion. Domain layer is framework-agnostic.\n  > WHY: Testable business logic that survives framework changes.\n- Repository pattern for data access. Never call ORM directly from business logic.\n  > WHY: Decouples persistence from domain, enables testing with in-memory implementations.\n- React Query for server state, Zustand for client state. No Redux.\n  > WHY: Lighter weight, better TypeScript support, less boilerplate.\n\n## Error Handling\n- Custom AppError hierarchy with HTTP status codes. Throw for exceptional, return Result for expected failures.\n  > WHY: Clear intent — callers know which errors to catch vs handle.\n- Structured logging with Winston. Never log sensitive data (passwords, tokens, PII).\n  > WHY: Observability without security risk. Structured logs enable alerting.\n\n## Testing\n- 80% unit coverage, 100% critical paths. Use factory functions for test data.\n  > WHY: Factory functions are maintainable and composable. Fixtures become stale.\n- Mock only external dependencies (APIs, DB). Never mock internal logic.\n  > WHY: Tests should reflect reality. Over-mocking hides real bugs.\n\n## Security\n- Validate all input with Zod schemas at API boundaries.\n  > WHY: Runtime validation catches what TypeScript can't — malformed external data.\n- Rate limit all public endpoints. Use helmet middleware.\n  > WHY: Defense in depth against abuse and common web vulnerabilities.\n\n## Git\n- Max 400 lines per PR. Conventional commits: feat/fix/refactor/test/docs.\n  > WHY: Small PRs get reviewed faster and have fewer bugs.\n</yakaai_skills>"}