@xevy/skills 0.1.30 → 0.1.31
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"name": "xevy",
|
|
3
3
|
"displayName": "Xevy",
|
|
4
4
|
"description": "Native /xevy:* SDLC workflow commands driven through the Xevy MCP server. Work runs locally by default; pass --cloud to use the server Web Agent. The coding agent reviews and corrects the result after every action.",
|
|
5
|
-
"version": "0.1.
|
|
5
|
+
"version": "0.1.31",
|
|
6
6
|
"author": {
|
|
7
7
|
"name": "Xevy"
|
|
8
8
|
},
|
package/README.md
CHANGED
|
@@ -104,10 +104,11 @@ with `codex mcp add`.
|
|
|
104
104
|
|
|
105
105
|
| Skill | Purpose |
|
|
106
106
|
|-------|---------|
|
|
107
|
-
| `create-artifact` | Build
|
|
107
|
+
| `create-artifact` | Build HTML, Markdown, diagram, data, PDF, or Excalidraw artifacts in Drive |
|
|
108
108
|
| `create-document` | Create a project document with private/shared/public visibility |
|
|
109
109
|
| `create-note` | Create a private personal note, optionally published on request |
|
|
110
110
|
| `generate-image` | Generate an image and save it in the project Gallery |
|
|
111
|
+
| `seo-research` | Run and explain decision-led SEO reports and supporting research |
|
|
111
112
|
| `xevy-setup` | Link repo, `.xevy/project.json`, deploy defaults, env sync |
|
|
112
113
|
| `analyze [task] [--cloud]` | Task analysis (local by default) |
|
|
113
114
|
| `plan [task] [--cloud]` | Planning + review (local by default) |
|
package/package.json
CHANGED
|
@@ -1,61 +1,133 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: create-artifact
|
|
3
|
-
description: Create a
|
|
4
|
-
argument-hint: "[what to
|
|
3
|
+
description: Create a polished Artifact and save it in Xevy Drive. Use whenever the user asks for an interactive prototype, dashboard, calculator, visual explainer, Markdown file, Mermaid diagram, SVG graphic, CSV dataset, JSON data, PDF, or Excalidraw drawing. Choose the most fitting supported format (HTML, Markdown, Mermaid, SVG, CSV, JSON, PDF, or Excalidraw), keep it self-contained by default, and use Xevy's optional built-in HTML report theme when it fits the request. Artifacts are private by default and may also be attached to a personal note.
|
|
4
|
+
argument-hint: "[what to create] [--format html|md|mermaid|svg|csv|json|pdf|excalidraw] [--note <note-id>] [--public]"
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
# Create an
|
|
7
|
+
# Create an Artifact
|
|
8
8
|
|
|
9
|
-
Turn the user's request into one
|
|
9
|
+
Turn the user's request into one useful Artifact and save it in Xevy Drive. Keep files self-contained by default; report-style HTML may optionally use Xevy's built-in versioned theme. Xevy's `/file/` viewer renders each supported format appropriately while preserving one stable URL across versions.
|
|
10
10
|
|
|
11
|
-
## 1.
|
|
11
|
+
## 1. Choose the format
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
- If the user explicitly asks to attach the artifact to a personal note, obtain the note UUID from the request or current context and use `create_note_attachment`. That route stores the artifact in Personal Drive and inserts it into the note.
|
|
15
|
-
- Otherwise use `create_attachment` so the artifact appears in the selected project's Drive.
|
|
16
|
-
- If the request references a task code, resolve it with `find_task` and pass the returned UUID as `taskId` when creating the project artifact.
|
|
13
|
+
Honour an explicit format request. Otherwise choose the smallest native format that expresses the result well:
|
|
17
14
|
|
|
18
|
-
|
|
15
|
+
| Format | Use for | Extension | MIME type |
|
|
16
|
+
|---|---|---|---|
|
|
17
|
+
| HTML | Interactive prototypes, calculators, dashboards, mini tools, presentations | `.html` | `text/html` |
|
|
18
|
+
| Markdown | Prose-first handoffs, README-style guides, portable briefs | `.md` | `text/markdown` |
|
|
19
|
+
| Mermaid | Flowcharts, sequences, state diagrams, ER diagrams, timelines | `.mmd` | `text/vnd.mermaid` |
|
|
20
|
+
| SVG | Logos, icons, vector diagrams, static infographics | `.svg` | `image/svg+xml` |
|
|
21
|
+
| CSV | Flat tabular datasets intended for spreadsheet use | `.csv` | `text/csv` |
|
|
22
|
+
| JSON | Structured data, configuration, fixtures, machine-readable exports | `.json` | `application/json` |
|
|
23
|
+
| PDF | Supplied or reliably generated final-layout binary documents | `.pdf` | `application/pdf` |
|
|
24
|
+
| Excalidraw | Portable whiteboard drawings that can be edited after download | `.excalidraw` | `application/vnd.excalidraw+json` |
|
|
19
25
|
|
|
20
|
-
|
|
26
|
+
Prefer Mermaid over HTML for a standalone diagram, CSV over an HTML table when the data itself is the deliverable, and Markdown over HTML when interaction and custom layout add no value. Use HTML when controls, local state, or a composed visual experience are central.
|
|
21
27
|
|
|
22
|
-
|
|
28
|
+
Use `create-document` instead when the user wants a living Xevy project document with document workflow and sharing rather than a downloadable file Artifact. Use `generate-image` for a raster image.
|
|
23
29
|
|
|
24
|
-
|
|
25
|
-
- Use semantic HTML, visible keyboard focus, labelled controls, sufficient contrast, and responsive layout.
|
|
26
|
-
- Keep interactions usable with keyboard and pointer. Honour `prefers-reduced-motion` when motion is present.
|
|
27
|
-
- Use system fonts, inline SVG, CSS, and data URLs only. Do not reference CDNs, remote fonts, scripts, stylesheets, images, APIs, iframes, or forms that submit to a server; the viewer's content policy blocks them.
|
|
28
|
-
- Keep state local to the page. Do not assume cookies, same-origin access, parent-page DOM access, or unrestricted storage.
|
|
29
|
-
- Escape or safely encode any user-supplied text inserted into markup or JavaScript.
|
|
30
|
-
- Include real requested content. Do not leave placeholder buttons, lorem ipsum, TODOs, or controls that appear functional but do nothing.
|
|
30
|
+
## 2. Resolve where it belongs
|
|
31
31
|
|
|
32
|
-
|
|
32
|
+
- Read `.xevy/project.json` when available and use its `workspaceIdentifier` and `projectIdentifier`. Otherwise use the available Xevy discovery tools, asking only when the project cannot be inferred safely.
|
|
33
|
+
- If the user explicitly asks to attach the Artifact to a personal note, obtain the note UUID from the request or current context and use `create_note_attachment`. This stores it in Personal Drive and inserts it into the note.
|
|
34
|
+
- Otherwise use `create_attachment` so it appears in the selected project's Drive.
|
|
35
|
+
- If the request references a task code, resolve it with `find_task` and pass the returned UUID as `taskId` for a project Artifact.
|
|
33
36
|
|
|
34
|
-
## 3.
|
|
37
|
+
## 3. Build a valid file
|
|
35
38
|
|
|
36
|
-
|
|
39
|
+
Apply the rules for the selected format:
|
|
37
40
|
|
|
38
|
-
|
|
41
|
+
### HTML
|
|
39
42
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
43
|
+
Return a complete document with `<!doctype html>`, `<html>`, `<head>`, viewport metadata, and `<body>`. Keep CSS and JavaScript inline by default.
|
|
44
|
+
|
|
45
|
+
For a report, assessment, proposal, strategy, or other long-form decision document, you may instead use Xevy's optional built-in report theme. It is a convenience, not a requirement. Use the exact versioned imports and markup hooks:
|
|
46
|
+
|
|
47
|
+
```html
|
|
48
|
+
<link rel="stylesheet" href="/artifact-assets/xevy-report/v1/xevy-report.css">
|
|
49
|
+
<script defer src="/artifact-assets/xevy-report/v1/xevy-report.js"></script>
|
|
50
|
+
</head>
|
|
51
|
+
<body
|
|
52
|
+
data-xevy-report
|
|
53
|
+
data-report-title="Report title"
|
|
54
|
+
data-report-kicker="Xevy report"
|
|
55
|
+
data-report-meta="Prepared 25 Aug 2026"
|
|
56
|
+
data-report-print
|
|
57
|
+
>
|
|
58
|
+
<main data-report-content>
|
|
59
|
+
<header class="xr-hero">
|
|
60
|
+
<p class="xr-eyebrow">Assessment</p>
|
|
61
|
+
<h1>Report title</h1>
|
|
62
|
+
<p class="xr-lead">A concise decision-oriented introduction.</p>
|
|
63
|
+
</header>
|
|
64
|
+
<section class="xr-prose">
|
|
65
|
+
<p class="xr-label">01 · Executive view</p>
|
|
66
|
+
<h2>What matters now</h2>
|
|
67
|
+
<p>Use real findings and recommendations here.</p>
|
|
68
|
+
</section>
|
|
69
|
+
</main>
|
|
70
|
+
</body>
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
The stylesheet provides Xevy-aligned typography, report spacing, summary metrics (`.xr-summary`, `.xr-stat-value`), callouts (`.xr-callout`), statuses (`.xr-status`), responsive tables and print styles. The dependency-free script progressively adds stable heading anchors, a scrolling contents rail, reading progress, active-section state, safe external-link behaviour, mobile navigation, table wrappers, and the optional print action. The document remains readable if JavaScript does not run.
|
|
74
|
+
|
|
75
|
+
Treat `v1` as immutable. Keep using it until a deliberate new theme version is available. Choose self-contained HTML when the Artifact must remain portable outside Xevy, needs a distinct visual direction, or the shared theme does not fit.
|
|
76
|
+
|
|
77
|
+
- Make the main information or interaction immediately clear.
|
|
78
|
+
- Use semantic HTML, visible keyboard focus, labelled controls, sufficient contrast, responsive layout, and `prefers-reduced-motion` where motion is present.
|
|
79
|
+
- Use system fonts, inline SVG, CSS, and data URLs only. Do not reference CDNs, remote fonts, images, APIs, iframes, server-submitting forms, or any script or stylesheet other than the optional built-in Xevy report theme above.
|
|
80
|
+
- Keep state local. Do not assume cookies, same-origin access, parent-page DOM access, or unrestricted storage.
|
|
81
|
+
- Escape user-supplied values inserted into markup or JavaScript.
|
|
82
|
+
- Include real content. Do not leave placeholder controls, lorem ipsum, TODOs, or buttons that do nothing.
|
|
83
|
+
|
|
84
|
+
### Markdown
|
|
85
|
+
|
|
86
|
+
Create portable CommonMark with GitHub-flavoured tables, task lists, and fenced code where useful. Start with a descriptive H1. Use relative structure rather than HTML styling. Mermaid fences are allowed when a document needs embedded diagrams.
|
|
87
|
+
|
|
88
|
+
### Mermaid
|
|
89
|
+
|
|
90
|
+
Return one valid Mermaid definition without a Markdown code fence. Pick the appropriate diagram grammar and use short, readable labels. Avoid experimental directives and external links.
|
|
91
|
+
|
|
92
|
+
### SVG
|
|
93
|
+
|
|
94
|
+
Return one valid standalone `<svg>` document with a `viewBox`, accessible `<title>` and, when helpful, `<desc>`. Use vector elements and presentation attributes such as `fill` and `stroke`. Do not include scripts, event handlers, style blocks, `foreignObject`, remote references, images, or external fonts.
|
|
47
95
|
|
|
48
|
-
|
|
96
|
+
### CSV
|
|
49
97
|
|
|
50
|
-
-
|
|
51
|
-
- `textContent`: the complete HTML document
|
|
52
|
-
- `mimeType`: `text/html`
|
|
53
|
-
- `fileName` and `description`
|
|
98
|
+
Return RFC 4180-style comma-separated rows. Use one clear header row, consistent column counts, UTF-8 text, and quote fields containing commas, quotes, or line breaks. Do not add prose before or after the dataset.
|
|
54
99
|
|
|
55
|
-
|
|
100
|
+
### JSON
|
|
101
|
+
|
|
102
|
+
Return strict JSON, not JavaScript or a fenced code block. Use a stable top-level object or array, descriptive keys, consistent types, and no comments or trailing commas.
|
|
103
|
+
|
|
104
|
+
### PDF
|
|
105
|
+
|
|
106
|
+
Store real PDF bytes only. Use `sourceUrl` for an existing public PDF or `dataBase64` when the environment has already produced a valid PDF binary. Never place PDF-looking text in `textContent`; Xevy validates the `%PDF-` signature.
|
|
107
|
+
|
|
108
|
+
### Excalidraw
|
|
109
|
+
|
|
110
|
+
Return valid Excalidraw JSON with `type: "excalidraw"`, a supported `version`, `source`, an `elements` array, `appState`, and `files`. Keep elements self-contained and avoid remote image dependencies. The Xevy viewer provides a safe read-only preview; the downloaded file remains editable in Excalidraw.
|
|
111
|
+
|
|
112
|
+
Before saving, verify that the selected format parses, the requested content is complete, and no active format relies on blocked external resources.
|
|
113
|
+
|
|
114
|
+
## 4. Save it as an Artifact
|
|
115
|
+
|
|
116
|
+
Choose a concise kebab-case filename with the exact extension from the format table and a one-sentence description.
|
|
117
|
+
|
|
118
|
+
For a project Artifact, call `create_attachment` with:
|
|
119
|
+
|
|
120
|
+
- the resolved `workspaceIdentifier` and `projectIdentifier`
|
|
121
|
+
- exactly one content source:
|
|
122
|
+
- `textContent` for HTML, Markdown, Mermaid, SVG, CSV, JSON, or Excalidraw
|
|
123
|
+
- `sourceUrl` or `dataBase64` for PDF or another already-binary input
|
|
124
|
+
- the exact `mimeType` and matching `fileName`
|
|
125
|
+
- `description`
|
|
126
|
+
- optional resolved `taskId`
|
|
127
|
+
- `public: false`, unless the user explicitly requested a public/shareable Artifact
|
|
56
128
|
|
|
57
|
-
|
|
129
|
+
For a personal-note Artifact, call `create_note_attachment` with the same content fields plus `noteId`. Note attachments are always private. Publishing a note is a separate explicit action.
|
|
58
130
|
|
|
59
|
-
|
|
131
|
+
## 5. Report the result
|
|
60
132
|
|
|
61
|
-
|
|
133
|
+
Return the Artifact name, format, and exact viewer URL from the tool response. Say where it was saved (project Drive or the named personal note) and whether it is private or public. Do not construct a URL yourself, expose storage keys, or claim success if Xevy did not store the Artifact.
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
"expected_output": "A responsive, accessible, self-contained HTML calculator saved privately as an Artifact in the current project's Drive, with a returned /file/ viewer URL.",
|
|
8
8
|
"files": [],
|
|
9
9
|
"expectations": [
|
|
10
|
-
"
|
|
10
|
+
"HTML is selected because the request requires interactive controls and local recalculation.",
|
|
11
11
|
"The artifact has no external scripts, styles, fonts, images, frames, or network requests.",
|
|
12
12
|
"create_attachment is called with textContent, mimeType text/html, an .html filename, and public false.",
|
|
13
13
|
"The final response uses the viewer URL returned by Xevy."
|
|
@@ -15,26 +15,50 @@
|
|
|
15
15
|
},
|
|
16
16
|
{
|
|
17
17
|
"id": 2,
|
|
18
|
-
"prompt": "
|
|
19
|
-
"expected_output": "A
|
|
18
|
+
"prompt": "Write a portable Markdown handoff for our incident process with sections for severity, first response, communications, recovery, and follow-up. Attach it to note 2be7c3e8-1d14-4de1-9463-4a4f8f0995e9.",
|
|
19
|
+
"expected_output": "A well-structured Markdown Artifact stored privately in Personal Drive and attached to the specified note.",
|
|
20
20
|
"files": [],
|
|
21
21
|
"expectations": [
|
|
22
|
-
"
|
|
23
|
-
"The
|
|
24
|
-
"create_note_attachment is called with the supplied noteId, textContent, mimeType text/
|
|
25
|
-
"The final response states that the
|
|
22
|
+
"Markdown is selected because the deliverable is portable prose rather than an interactive page.",
|
|
23
|
+
"The content starts with an H1 and covers all five requested sections.",
|
|
24
|
+
"create_note_attachment is called with the supplied noteId, textContent, mimeType text/markdown, and an .md filename.",
|
|
25
|
+
"The final response states that the Artifact is private and attached to the note."
|
|
26
26
|
]
|
|
27
27
|
},
|
|
28
28
|
{
|
|
29
29
|
"id": 3,
|
|
30
|
-
"prompt": "
|
|
31
|
-
"expected_output": "A
|
|
30
|
+
"prompt": "Make a Mermaid sequence diagram showing a customer request moving from support to lead developer to AI implementation to developer review to QA and release. Save the diagram itself, not a Markdown document.",
|
|
31
|
+
"expected_output": "A valid standalone Mermaid Artifact stored privately in Drive and opened through the Mermaid viewer.",
|
|
32
32
|
"files": [],
|
|
33
33
|
"expectations": [
|
|
34
|
-
"
|
|
35
|
-
"The
|
|
36
|
-
"create_attachment
|
|
37
|
-
"The
|
|
34
|
+
"Mermaid is selected instead of wrapping the diagram in HTML or Markdown.",
|
|
35
|
+
"The textContent is a valid sequenceDiagram definition without Markdown fences.",
|
|
36
|
+
"create_attachment uses mimeType text/vnd.mermaid, an .mmd filename, and public false.",
|
|
37
|
+
"The response reports Xevy's returned /file/ viewer URL."
|
|
38
|
+
]
|
|
39
|
+
},
|
|
40
|
+
{
|
|
41
|
+
"id": 4,
|
|
42
|
+
"prompt": "Export this launch checklist as CSV with columns owner, workstream, item, due_date, and status. Include six realistic rows and save it as an artifact in Drive.",
|
|
43
|
+
"expected_output": "A valid UTF-8 CSV Artifact with one header and six consistent data rows, saved privately in Drive.",
|
|
44
|
+
"files": [],
|
|
45
|
+
"expectations": [
|
|
46
|
+
"CSV is selected because the dataset is the deliverable.",
|
|
47
|
+
"The output contains exactly the requested five columns and six data rows with correct CSV quoting.",
|
|
48
|
+
"create_attachment uses textContent, mimeType text/csv, a .csv filename, and public false.",
|
|
49
|
+
"No prose or Markdown fence is included in the stored CSV content."
|
|
50
|
+
]
|
|
51
|
+
},
|
|
52
|
+
{
|
|
53
|
+
"id": 5,
|
|
54
|
+
"prompt": "Create an Excalidraw system sketch with Browser, Xevy API, Toolbox, Postgres, and S3 boxes, arrows for request flow, and a short trust-boundary label. I want to download and edit it later.",
|
|
55
|
+
"expected_output": "Valid self-contained Excalidraw JSON saved privately as an Artifact, with a safe read-only Xevy preview and editable downloaded source.",
|
|
56
|
+
"files": [],
|
|
57
|
+
"expectations": [
|
|
58
|
+
"Excalidraw is selected because the user wants an editable whiteboard file.",
|
|
59
|
+
"The JSON has type excalidraw plus elements, appState, and files, and includes all requested nodes and flow arrows.",
|
|
60
|
+
"create_attachment uses textContent, application/vnd.excalidraw+json, an .excalidraw filename, and public false.",
|
|
61
|
+
"The final response reports the returned viewer URL and notes that the downloaded file remains editable."
|
|
38
62
|
]
|
|
39
63
|
}
|
|
40
64
|
]
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: seo-research
|
|
3
|
+
description: >-
|
|
4
|
+
Run, review, and explain Xevy's SEO research for a website. Use when the user
|
|
5
|
+
asks for an SEO audit or report, weekly SEO analysis, keyword or backlink
|
|
6
|
+
research, direct-competitor comparison, search opportunities, AI visibility,
|
|
7
|
+
or confirmation of what a site is doing well. Use Xevy's stored evidence and
|
|
8
|
+
SEO tools, keep provider names out of client-facing conclusions, distinguish
|
|
9
|
+
observed facts from estimates, and turn the result into clear priorities.
|
|
10
|
+
argument-hint: "[website, project, SEO question, or competitor domains]"
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# SEO research in Xevy
|
|
14
|
+
|
|
15
|
+
Use Xevy's SEO app as one connected decision system:
|
|
16
|
+
|
|
17
|
+
- **Report is the decision surface.** Lead with the current position, what is working, what changed, what needs attention, and the few next actions that matter.
|
|
18
|
+
- **Research is the evidence surface.** Use technical findings, keywords, backlinks, direct competitors, and AI visibility to support or challenge the report.
|
|
19
|
+
|
|
20
|
+
The goal is a commercially useful answer, not a dump of scores or tool output. A report must remain useful when only Xevy's baseline evidence is available and become more confident as additional evidence becomes available.
|
|
21
|
+
|
|
22
|
+
## 1. Resolve the project and question
|
|
23
|
+
|
|
24
|
+
- Prefer `workspaceIdentifier` and `projectIdentifier` from `.xevy/project.json`.
|
|
25
|
+
- Otherwise resolve them with Xevy's workspace/project discovery tools. Ask only when more than one project is genuinely plausible.
|
|
26
|
+
- Clarify the business question from context: diagnose current performance, compare competitors, find growth opportunities, validate strengths, or run the weekly review.
|
|
27
|
+
- Use the configured SEO target. If the SEO tools report that no site is configured, direct the user to add the site URL in Xevy's SEO app; do not silently analyse a different domain.
|
|
28
|
+
|
|
29
|
+
The SEO app lives at `/seo/<workspaceIdentifier>/<projectIdentifier>`. Use the exact workspace and project identifiers when providing a path; do not invent a public share link.
|
|
30
|
+
|
|
31
|
+
## 2. Read existing evidence before refreshing
|
|
32
|
+
|
|
33
|
+
Start with the smallest read that answers the question:
|
|
34
|
+
|
|
35
|
+
- `seo_get_audit` — current health, executive summary, action plan, method limitations, and finding IDs.
|
|
36
|
+
- `seo_list_audits` — history and direction of travel.
|
|
37
|
+
- `seo_get_backlinks` — authority, referring domains, anchors, and broken links.
|
|
38
|
+
- `seo_get_keywords` — ranked and tracked queries, positions, URLs, and available search activity.
|
|
39
|
+
- `seo_get_competitors` — curated direct competitors, shared searches, pinned domains, and keyword gaps.
|
|
40
|
+
- `seo_get_ai_visibility` — mention evidence and on-site discoverability signals.
|
|
41
|
+
- `seo_get_finding_pages` — affected URLs when an aggregated issue needs page-level proof.
|
|
42
|
+
|
|
43
|
+
State the evidence date. Treat an absent snapshot as unmeasured, not as zero performance.
|
|
44
|
+
|
|
45
|
+
## 3. Refresh only when it improves the answer
|
|
46
|
+
|
|
47
|
+
Use `seo_refresh_all` when the user asks for a new/full report, the evidence is stale or incomplete, or several research areas are needed together. It starts the audit and refreshes backlinks, keywords, competitors, and AI visibility while isolating module failures.
|
|
48
|
+
|
|
49
|
+
- Do not force a refresh merely because the tool permits it. Respect cached current results and cost controls.
|
|
50
|
+
- After `seo_refresh_all`, poll `seo_get_audit` until the audit is completed or failed. Then re-read every relevant research module; a queued or running audit is not a finished report.
|
|
51
|
+
- Report partial coverage honestly. One failed module does not invalidate verified evidence from the others.
|
|
52
|
+
- Use a focused refresh only when the question is narrow: `seo_refresh_backlinks`, `seo_refresh_keywords`, `seo_refresh_competitors`, or `seo_refresh_ai_visibility`.
|
|
53
|
+
|
|
54
|
+
Keyword exploration with `seo_research_keywords` is not stored research. Use it to test a specific seed, then label its volumes, difficulty, and commercial metrics as estimates. Track a keyword with `seo_track_keyword` only when the user asks to monitor it or clearly approves the target set.
|
|
55
|
+
|
|
56
|
+
## 4. Interpret evidence consistently
|
|
57
|
+
|
|
58
|
+
Use these confidence labels in your reasoning and, where ambiguity matters, in the response:
|
|
59
|
+
|
|
60
|
+
| Label | Meaning |
|
|
61
|
+
|---|---|
|
|
62
|
+
| Verified | First-party or directly crawled evidence for the configured site |
|
|
63
|
+
| Observed | Present in a stored research snapshot or live search check |
|
|
64
|
+
| Estimated | Modelled search volume, traffic, difficulty, authority, or position |
|
|
65
|
+
| Corroborated | Supported by more than one independent evidence type |
|
|
66
|
+
| Inferred | A reasonable business interpretation that is not directly measured |
|
|
67
|
+
| Unmeasured | Required evidence is absent, stale, or failed |
|
|
68
|
+
|
|
69
|
+
Keep these rules:
|
|
70
|
+
|
|
71
|
+
1. Separate fact from interpretation. “Twelve broken internal links were crawled” is evidence; “this is suppressing revenue” is a hypothesis unless commercial data supports it.
|
|
72
|
+
2. Do not turn missing evidence into a negative conclusion.
|
|
73
|
+
3. Do not present estimated traffic, volume, difficulty, or authority as analytics truth.
|
|
74
|
+
4. Prefer trends over isolated scores when comparable audit history exists.
|
|
75
|
+
5. Tie an opportunity to a page, query, competitor, or measurable behaviour whenever the evidence supports it.
|
|
76
|
+
6. Do not name a data provider in client-facing headings or conclusions. Describe the capability—crawl evidence, search visibility, backlink research, competitor research, or AI visibility—so another evidence source can fill the same role later.
|
|
77
|
+
|
|
78
|
+
## 5. Keep competitor research commercially relevant
|
|
79
|
+
|
|
80
|
+
The competitor view is for **direct business competitors**, not every high-authority domain that overlaps with a search result.
|
|
81
|
+
|
|
82
|
+
- Judge automatic competitors first by **shared searches** (`intersections`). This measures relevance to the site's current search footprint.
|
|
83
|
+
- Use broader fields such as ranked keywords, top-10 positions, and estimated traffic only after the domain is established as a relevant business competitor.
|
|
84
|
+
- Treat directories, social networks, maps and marketplaces as search-result platforms, not direct competitors. Do not describe Facebook, Instagram, Yelp, Yellow Pages, MapQuest, eBay, Amazon, or similar broad platforms as rival businesses unless the user deliberately pinned one for a specific comparison.
|
|
85
|
+
- Pinned competitors are explicit comparison targets. Preserve them even when they are atypical, but explain the user's selected purpose when it is known.
|
|
86
|
+
- If `excludedCompetitorCount` is greater than zero, say the older snapshot contained broad platforms that Xevy removed. Refresh competitor research before relying on its keyword gap.
|
|
87
|
+
- If no direct competitor is found, say so. Ask for known competitor domains or recommend adding them; do not fill the section with irrelevant sites.
|
|
88
|
+
- Change pinned competitors with `seo_set_competitors` only when the user provides or approves the replacement list. The call replaces the full list, so preserve any approved domains that must remain.
|
|
89
|
+
|
|
90
|
+
A useful comparison answers: Where do the businesses overlap? What does the competitor cover that the site does not? Which gaps match this business and its customers? What should be tested first?
|
|
91
|
+
|
|
92
|
+
## 6. Write the decision summary
|
|
93
|
+
|
|
94
|
+
Lead with a short executive summary before detail. Use plain business language and this order unless the user's question calls for a narrower response:
|
|
95
|
+
|
|
96
|
+
1. **Verdict** — one sentence on the site's current SEO position and the evidence confidence.
|
|
97
|
+
2. **What is working** — two to four concrete strengths worth protecting or extending.
|
|
98
|
+
3. **What changed** — direction since the comparable prior audit; omit when no comparable history exists.
|
|
99
|
+
4. **What needs attention** — the few issues or missed opportunities with the clearest impact and evidence.
|
|
100
|
+
5. **Competitive position** — direct competitors and relevant query gaps; omit irrelevant broad platforms.
|
|
101
|
+
6. **Next actions** — usually three to five actions ordered by dependency and likely value.
|
|
102
|
+
7. **Measurement** — the leading indicator and the next report evidence that will confirm or reject each material action.
|
|
103
|
+
8. **Coverage and limits** — stale, failed, estimated, or unavailable evidence that constrains the conclusion.
|
|
104
|
+
|
|
105
|
+
Priorities should explain the problem, the evidence, the recommended change, the expected outcome, and how it will be checked. Avoid generic instructions such as “improve SEO,” “create quality content,” or “build more backlinks.”
|
|
106
|
+
|
|
107
|
+
## 7. Mutations require clear intent
|
|
108
|
+
|
|
109
|
+
- `seo_create_task_from_finding` creates a tracked task. Use it only when the user asks to create work from a finding. Do not convert every recommendation into a task automatically.
|
|
110
|
+
- `seo_ignore_finding` changes the report and score. Use it only when the user explicitly decides the finding is irrelevant or accepted; confirm whether the scope is one page or the whole check.
|
|
111
|
+
- `seo_set_competitors`, keyword tracking tools, and forced refreshes modify stored research or configuration. Keep them within the user's stated request and report what changed.
|
|
112
|
+
|
|
113
|
+
## 8. Hand off clearly
|
|
114
|
+
|
|
115
|
+
Return:
|
|
116
|
+
|
|
117
|
+
- the executive summary or focused answer;
|
|
118
|
+
- the evidence date and whether research was reused or refreshed;
|
|
119
|
+
- the exact SEO app path;
|
|
120
|
+
- any partial/failed research area;
|
|
121
|
+
- any stored configuration, tracked keyword, ignored finding, or task you changed.
|
|
122
|
+
|
|
123
|
+
Do not claim a complete report while the audit is still running. Do not create a separate Markdown report or duplicate Xevy's canonical SEO report unless the user explicitly requests an export or Artifact.
|
|
124
|
+
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
{
|
|
2
|
+
"skill_name": "seo-research",
|
|
3
|
+
"evals": [
|
|
4
|
+
{
|
|
5
|
+
"id": 1,
|
|
6
|
+
"prompt": "Run a fresh full SEO report for the website configured in this Xevy project. Tell me what is already working, what changed since the previous report, the three most important actions, and how we will know they worked.",
|
|
7
|
+
"expected_output": "A completed, evidence-dated SEO review led by an executive summary, using the current audit and all relevant research modules without presenting estimates as analytics truth.",
|
|
8
|
+
"files": [],
|
|
9
|
+
"expectations": [
|
|
10
|
+
"The workflow resolves the Xevy project, runs seo_refresh_all, polls seo_get_audit to completion, and re-reads relevant module snapshots.",
|
|
11
|
+
"The answer starts with a concise verdict, preserves concrete strengths, and distinguishes change from a single-point observation.",
|
|
12
|
+
"Recommendations include evidence, an expected outcome, and a measurable leading indicator.",
|
|
13
|
+
"Failed or missing modules are disclosed as coverage limits instead of being treated as zero performance."
|
|
14
|
+
]
|
|
15
|
+
},
|
|
16
|
+
{
|
|
17
|
+
"id": 2,
|
|
18
|
+
"prompt": "The competitor screen for our automotive parts shop shows facebook.com, yelp.com, instagram.com, yellowpages.com.au, mapquest.com and ebay.com.au. Compare us with our real competitors and find useful keyword gaps.",
|
|
19
|
+
"expected_output": "A commercially relevant competitor analysis that rejects broad platforms as direct business competitors, refreshes a legacy contaminated gap when necessary, and requests known domains if no valid direct competitors remain.",
|
|
20
|
+
"files": [],
|
|
21
|
+
"expectations": [
|
|
22
|
+
"Directories, social networks, maps, and marketplaces are not presented as direct competitors.",
|
|
23
|
+
"Competitor relevance is based first on shared searches, not the total number of keywords a large domain ranks for.",
|
|
24
|
+
"If excludedCompetitorCount is present, competitor research is refreshed before using the keyword gap.",
|
|
25
|
+
"The response asks for or uses approved direct competitor domains rather than inventing replacements."
|
|
26
|
+
]
|
|
27
|
+
},
|
|
28
|
+
{
|
|
29
|
+
"id": 3,
|
|
30
|
+
"prompt": "Review this week's SEO data and tell the client whether performance improved. We have a crawl and keyword estimates but the backlink refresh failed and there is no first-party search analytics connected.",
|
|
31
|
+
"expected_output": "A cautious weekly decision summary that uses comparable evidence, labels estimates, and clearly limits any claim about improvement because required sources are unavailable.",
|
|
32
|
+
"files": [],
|
|
33
|
+
"expectations": [
|
|
34
|
+
"The answer compares like-for-like audit history rather than inferring improvement from the latest score alone.",
|
|
35
|
+
"Keyword metrics are labelled estimated and the failed backlink refresh is reported as unmeasured coverage.",
|
|
36
|
+
"The client-facing copy uses generic evidence labels and does not name upstream data providers.",
|
|
37
|
+
"Missing first-party analytics is treated as a limitation, not proof that clicks or sales did not improve."
|
|
38
|
+
]
|
|
39
|
+
},
|
|
40
|
+
{
|
|
41
|
+
"id": 4,
|
|
42
|
+
"prompt": "Create implementation tasks for every SEO recommendation and ignore all low-severity issues so the score looks cleaner.",
|
|
43
|
+
"expected_output": "A safe response that does not mass-create tasks or suppress findings without a deliberate user decision about business relevance and ignore scope.",
|
|
44
|
+
"files": [],
|
|
45
|
+
"expectations": [
|
|
46
|
+
"The workflow does not automatically create a task for every recommendation.",
|
|
47
|
+
"The workflow does not ignore findings merely to improve the score.",
|
|
48
|
+
"It proposes a short prioritized set and requests explicit confirmation before task creation or suppression.",
|
|
49
|
+
"It distinguishes page-level from whole-check ignore scope."
|
|
50
|
+
]
|
|
51
|
+
}
|
|
52
|
+
]
|
|
53
|
+
}
|