Build One Set of SEO Research Skills That Works in Many AI Agent Tools

## Write Each Skill Once, Using Only What Every Tool Understands Author every research skill in a canonical, platform-neutral source. Limit the core contract to features that all intended agent environments can interpret. Require each skill definition to provide: - a stable name and clear description; - optional model and tool declarations only when the host supports them; - complete operating guidance in the body; - explicit inputs, outputs, constraints, and failure conditions. Treat platform-specific controls as optional extensions. A compatibility checker should warn when a host may ignore an extension without rejecting an otherwise portable skill. Edit the canonical source rather than generated platform copies. Validate all skill definitions before packaging or distribution so missing metadata and unsupported syntax fail early. ## Find Where Each AI Agent Tool Looks for Instructions and Skills Map how every target environment discovers project instructions and reusable skills. Common patterns include root instruction files, dedicated rule directories, native skill folders, generated dispatchers, and documentation fallbacks. For each host, record: - which file is read automatically at session start; - where reusable skills must be copied, linked, or installed; - whether activation is automatic or requires an explicit command; - how unsupported delegation falls back to inline execution; - which project documentation acts as the final fallback. Do not assume that one installation layout works everywhere. Preserve one semantic source while adapting discovery, activation, and packaging to the host's verified behavior. ## Write Steps as Plain Actions, Then Map Them to Each Tool's Names Write recipes in terms of neutral operations such as reading, writing, editing, executing commands, listing files, searching text, and fetching web content. Maintain a verified compatibility map from those operations to each host's tool names. Let adapters translate aliases when the host supports automatic mapping. When a capability is unavailable, define a documented fallback rather than silently dropping the step. Keep tool translation separate from research logic. A page-analysis recipe should state that it needs a protected fetch and an HTML parser, not depend on one vendor's tool labels. Review mappings whenever a host changes its tool interface. Do not claim compatibility from similar naming alone; exercise the mapped operation. ## Let a Small Main Skill Pick Which Research Skill to Load Use a small orchestrator to classify the request and load only the relevant capability. Keep detailed analysis logic in focused modules instead of one oversized instruction file. Separate the system into: - a routing skill that selects the workflow; - focused research skills with complete analysis criteria; - optional specialist agents for independent or parallel work; - local scripts for deterministic execution; - schema templates for structured search metadata; - adapters for host-specific packaging; - extensions for optional providers and expensive capabilities. Keep extensions outside the core dependency path. A missing extension must reduce optional coverage without breaking foundational research. ## Pick the Narrowest SEO Check for Each Question Select the narrowest capability that answers the research question: - use a full-site audit for broad discovery and prioritization; - use single-page analysis for deep examination of one URL; - use technical analysis for crawlability, indexing, performance, and related infrastructure; - use content analysis for quality, trust, expertise, and experience signals; - use structured-data analysis for detection, validation, and generation; - use sitemap analysis for XML coverage and generation; - use image analysis for on-page metadata, search-result visibility, and file optimization; - use AI-search analysis for generative visibility and answer-engine optimization. Escalate to a broader audit only when findings cross several capability boundaries. Preserve the original URL, evidence source, observation time, and uncertainty for every external claim. ## Keep SEO Planning Separate and Track Changes from a Starting Point Provide distinct workflows for strategic planning, semantic keyword clustering, search-experience analysis, and content architecture. Do not merge these planning tasks into technical diagnostics. Keep monitoring state explicit: 1. capture a stable baseline; 2. compare a later observation with that baseline; 3. retain history so repeated changes can be distinguished from one-time noise. Use specialized modules for commerce, programmatic landing pages, competitor comparison pages, local search, map visibility, international language targeting, first-party search data, page experience, and backlink analysis. Treat external data providers, large-scale crawling, and asset generation as optional extensions. Label provider requirements, credentials, cost, and coverage limits before invoking them. ## Check URLs Before Fetching and Keep API Keys Out of Skill Files Use local scripts for deterministic work such as protected page retrieval, HTML parsing, performance checks, baseline capture, and structured export. Every network-facing helper must validate its target URL before making a request to reduce server-side request forgery risk. Preserve certificate verification; investigate certificate failures instead of disabling transport security. Keep API credentials in a user-level configuration location or injected environment, never in canonical skills, sample outputs, or generated packages. Stop with a clear missing-credential result rather than inventing values. Run helpers through the configured language environment and dependency manager. When a cloud host does not expose that environment on `PATH`, use its verified absolute executable path. Return machine-readable results when another module consumes the output. Preserve absolute paths for screenshots or other files written to temporary directories. ## Test the Skills in Every Supported AI Agent Tool Before Sharing Run a portability scan across every canonical skill before packaging. Confirm required metadata, valid structure, and known host-specific features. For each supported environment, test: - root instruction discovery; - skill installation or linking; - explicit and automatic activation paths; - tool-name translation; - inline fallback when delegated agents are unavailable; - local helper execution; - generated routing and documentation fallbacks. Warnings must identify the feature, affected host, and expected degradation. An ignored optional field can remain compatible; a missing required instruction or unavailable core operation cannot. ## Look into Tool-Specific Errors Without Turning Off Safety Checks Treat host-specific failures as environment evidence, not as permission to weaken safeguards. - Investigate certificate-chain or name-resolution failures before changing code. - Use a verified virtual-environment executable when the default command path lacks dependencies. - Check documented temporary directories when screenshots or reports are not in the working directory. - Use absolute paths when artifacts cross process or container boundaries. - Replace unavailable remote integrations with documented local helpers only when they provide equivalent evidence. Record whether a limitation affects discovery, execution, delegation, networking, or artifact location. Keep the workaround in the adapter or operating note rather than contaminating canonical research logic. ## Finish Changes by Testing in Real Tools and Updating the Docs Before declaring a cross-platform research change complete: - review the canonical skill and every affected adapter; - rebuild generated routing and packages; - run the portability scan and relevant helper tests; - exercise representative hosts rather than relying on syntax inspection; - update the capability catalog, installation guidance, and architecture notes; - confirm optional extensions remain isolated; - review outputs for credentials, unsupported claims, and missing evidence. Report the capability changed, hosts verified, checks passed, warnings observed, fallbacks used, and validation that could not run. Do not claim full parity when a host ignores required behavior or when only one environment was tested.