add-agent-target

Purpose

Add Agent Target

Use this skill when the task is to add a brand-new supported agent target to this repository (built-in) or as an external plugin package.

Primary reference: docs/add-new-target-playbook.md is the step-by-step workflow (phases 1–9, file templates, verification gates). Open it first and follow it. This skill file is the contract — the non-negotiable rules, touchpoints, and completion bar. The playbook is how; this file is what and why.

Companion skill: add-global-mode-target — use only when extending global-mode support into an existing target that was built before global was a first-class contract. For new targets, global mode is part of this skill (scaffold wires it automatically).

When To Use

• The task is to add a tool not currently in src/targets/catalog/target-ids.ts
• Scope covers both project and global modes unless the target has no meaningful global surface
• Delivery is either built-in (in this repo) or external plugin (standalone npm package)

Do Not Use This Skill For

• Extending global-mode coverage on an existing target — use add-global-mode-target
• Changing capability levels for an existing target — update the target's descriptor directly
• Plugin feature work that doesn't add a new target id

Non-Negotiable Rules

MUST

• Search the internet for the target's current official file structure, config files, and example content before changing code.
• Prefer official docs and other primary sources. Use vendor examples or source code only when official docs are incomplete, and call that out explicitly.
• Separate the target product from the current assistant runtime before making format decisions. Do not confuse a generated target like codex-cli with Codex desktop/chat, or local CLI MCP config with app-managed connectors.
• Capture the target's real capability map for every canonical feature: rules, additionalRules, commands, agents, skills, mcp, hooks, ignore, permissions.
• Fill in the descriptor metadata block (displayName, category, officialUrl, shortDescription). This is required at compile time and drives every auto-generated tool list in README + website. The scaffold leaves TODO(agentsmesh-scaffold) markers — replace them with the values from your Phase 1 research before commit.
• When a feature is none but skills is native or embedded, evaluate whether supportsConversion should project that feature as skills. If the target reads skill bundles, commands and agents with no native surface should be projected as skills via supportsConversion: { commands: true, agents: true } and registered in src/config/core/conversions.ts with DEFAULT_*_TO_SKILLS. Do not add lint warnings for features that are projected as skills — only warn for features that are truly dropped.
• Start from agentsmesh target scaffold <id> when building a built-in target. Do not hand-write the 10 skeleton files the scaffold produces.
• Write failing tests first for every new behavior. Do not implement first and backfill later.
• Add unit, integration, and e2e coverage for the complete import and generate flow, including global scope when applicable.
• Add rich and realistic fixtures for the new target. Fixtures must resemble real projects, not toy placeholders.
• Cover all edge cases for the new target, including legacy paths, fallbacks, malformed files, partial support, and unsupported features.
• Wire descriptor capabilities for both project and global scope. New targets must include global mode unless the target has no global config surface at all, and that absence must be documented.
• Update every affected command surface and user-facing document so the new target is discoverable and accurately described.
• Update the compatibility matrix to reflect native, embedded, partial, or unsupported features. The matrix auto-builds from descriptor capabilities; pnpm matrix:verify must pass. The same script auto-generates the import-targets table, homepage tool list, and README tool list from descriptor metadata — no manual edits to those tables.
• Update init detection and import empty-state messaging for the new target when native files exist.
• Reuse existing capability-focused tests where possible; extend them instead of duplicating assertions across multiple files.
• Preserve the canonical .agentsmesh/ contract. If the target cannot represent a feature natively, model that explicitly instead of inventing fake native output.
• Ensure every internal file link or reference inside generated or imported Markdown artifacts is convertible through the shared reference-rewrite pipeline, just like the existing targets. Do not ship a new target unless canonical .agentsmesh/ references round-trip cleanly across that target's Markdown surfaces.
• Run the full verification stack, including the packaging gates (pnpm attw, pnpm publint, pnpm consumer-smoke), before claiming completion.
• Run the post-feature-qa skill before marking the task done.