@clickminded/coauthor-cli 0.0.8 → 0.0.9
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.
- package/README.md +5 -1
- package/dist/commands.js +79 -5
- package/package.json +3 -1
- package/scripts/postinstall.mjs +96 -0
- package/skills/agents/SKILL.md +55 -0
- package/skills/claude/SKILL.md +10 -1
- package/skills/codex/SKILL.md +10 -1
- package/skills/cursor/coauthor-cli.mdc +5 -0
package/README.md
CHANGED
|
@@ -91,6 +91,7 @@ Install one target at a time:
|
|
|
91
91
|
coauthor skills install codex
|
|
92
92
|
coauthor skills install claude
|
|
93
93
|
coauthor skills install cursor
|
|
94
|
+
coauthor skills install agents
|
|
94
95
|
```
|
|
95
96
|
|
|
96
97
|
Default install paths are:
|
|
@@ -98,8 +99,11 @@ Default install paths are:
|
|
|
98
99
|
- Codex: `~/.codex/skills/coauthor/SKILL.md`
|
|
99
100
|
- Claude: `./.claude/skills/coauthor/SKILL.md`
|
|
100
101
|
- Cursor: `./.cursor/rules/coauthor-cli.mdc`
|
|
102
|
+
- Agents: `./.agents/skills/coauthor/SKILL.md`
|
|
101
103
|
|
|
102
|
-
Use `--dry-run` to preview, `--force` to overwrite existing files, and `--cwd <path>` to install Claude/Cursor skills into a specific project.
|
|
104
|
+
Use `--dry-run` to preview, `--force` to overwrite existing files, and `--cwd <path>` to install project-local Claude/Cursor/Agents skills into a specific project.
|
|
105
|
+
|
|
106
|
+
Skill installs are recorded in `~/.config/coauthor/managed-skills.json`. Future npm package updates automatically refresh recorded skill files when they still match the previously installed template. If you edit a skill file by hand, the auto-update leaves it alone until you run `coauthor skills install <target> --force`.
|
|
103
107
|
|
|
104
108
|
## Common Commands
|
|
105
109
|
|
package/dist/commands.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { setTimeout as sleep } from 'node:timers/promises';
|
|
2
2
|
import { spawn } from 'node:child_process';
|
|
3
|
+
import { createHash } from 'node:crypto';
|
|
3
4
|
import { mkdir, readFile, writeFile } from 'node:fs/promises';
|
|
4
5
|
import { homedir } from 'node:os';
|
|
5
6
|
import { dirname, join, resolve } from 'node:path';
|
|
@@ -400,11 +401,12 @@ async function runOperationCommand(action, input, client) {
|
|
|
400
401
|
}
|
|
401
402
|
throw new Error('Usage: coauthor operation <list|show|status>');
|
|
402
403
|
}
|
|
403
|
-
const SKILL_NAMES = ['codex', 'claude', 'cursor'];
|
|
404
|
+
const SKILL_NAMES = ['codex', 'claude', 'cursor', 'agents'];
|
|
404
405
|
const SKILL_TEMPLATE_PATHS = {
|
|
405
406
|
codex: '../skills/codex/SKILL.md',
|
|
406
407
|
claude: '../skills/claude/SKILL.md',
|
|
407
408
|
cursor: '../skills/cursor/coauthor-cli.mdc',
|
|
409
|
+
agents: '../skills/agents/SKILL.md',
|
|
408
410
|
};
|
|
409
411
|
async function runSkillsCommand(action, input) {
|
|
410
412
|
if (!action || action === 'list') {
|
|
@@ -435,41 +437,112 @@ async function runSkillsCommand(action, input) {
|
|
|
435
437
|
data: { results },
|
|
436
438
|
};
|
|
437
439
|
}
|
|
438
|
-
throw new Error('Usage: coauthor skills <list|install> [codex|claude|cursor|all]');
|
|
440
|
+
throw new Error('Usage: coauthor skills <list|install> [codex|claude|cursor|agents|all]');
|
|
439
441
|
}
|
|
440
442
|
function resolveRequestedSkills(value) {
|
|
441
443
|
if (!value || value === 'all')
|
|
442
444
|
return [...SKILL_NAMES];
|
|
443
445
|
if (isSkillName(value))
|
|
444
446
|
return [value];
|
|
445
|
-
throw new Error('Usage: coauthor skills install <codex|claude|cursor|all>');
|
|
447
|
+
throw new Error('Usage: coauthor skills install <codex|claude|cursor|agents|all>');
|
|
446
448
|
}
|
|
447
449
|
function isSkillName(value) {
|
|
448
450
|
return SKILL_NAMES.includes(value);
|
|
449
451
|
}
|
|
450
452
|
async function installSkill(params) {
|
|
451
453
|
const targetPath = getSkillInstallPath(params.skill, params.cwd);
|
|
454
|
+
const templatePath = getSkillTemplatePath(params.skill);
|
|
455
|
+
const template = await readFile(templatePath, 'utf8');
|
|
456
|
+
const templateHash = sha256(template);
|
|
452
457
|
if (!params.force && await fileExists(targetPath)) {
|
|
458
|
+
const current = await readFile(targetPath, 'utf8');
|
|
459
|
+
if (sha256(current) === templateHash) {
|
|
460
|
+
await recordManagedSkill({
|
|
461
|
+
skill: params.skill,
|
|
462
|
+
path: targetPath,
|
|
463
|
+
template: getSkillTemplateRelativePath(params.skill),
|
|
464
|
+
templateHash,
|
|
465
|
+
});
|
|
466
|
+
}
|
|
453
467
|
return { skill: params.skill, status: 'skipped', path: targetPath };
|
|
454
468
|
}
|
|
455
469
|
if (params.dryRun) {
|
|
456
470
|
return { skill: params.skill, status: 'dry_run', path: targetPath };
|
|
457
471
|
}
|
|
458
|
-
const template = await readFile(getSkillTemplatePath(params.skill), 'utf8');
|
|
459
472
|
await mkdir(dirname(targetPath), { recursive: true });
|
|
460
473
|
await writeFile(targetPath, template, { mode: 0o644 });
|
|
474
|
+
await recordManagedSkill({
|
|
475
|
+
skill: params.skill,
|
|
476
|
+
path: targetPath,
|
|
477
|
+
template: getSkillTemplateRelativePath(params.skill),
|
|
478
|
+
templateHash,
|
|
479
|
+
});
|
|
461
480
|
return { skill: params.skill, status: 'installed', path: targetPath };
|
|
462
481
|
}
|
|
463
482
|
function getSkillTemplatePath(skill) {
|
|
464
|
-
return fileURLToPath(new URL(
|
|
483
|
+
return fileURLToPath(new URL(getSkillTemplateRelativePath(skill), import.meta.url));
|
|
484
|
+
}
|
|
485
|
+
function getSkillTemplateRelativePath(skill) {
|
|
486
|
+
return SKILL_TEMPLATE_PATHS[skill];
|
|
465
487
|
}
|
|
466
488
|
function getSkillInstallPath(skill, cwd) {
|
|
467
489
|
if (skill === 'codex')
|
|
468
490
|
return join(homedir(), '.codex', 'skills', 'coauthor', 'SKILL.md');
|
|
469
491
|
if (skill === 'claude')
|
|
470
492
|
return join(cwd, '.claude', 'skills', 'coauthor', 'SKILL.md');
|
|
493
|
+
if (skill === 'agents')
|
|
494
|
+
return join(cwd, '.agents', 'skills', 'coauthor', 'SKILL.md');
|
|
471
495
|
return join(cwd, '.cursor', 'rules', 'coauthor-cli.mdc');
|
|
472
496
|
}
|
|
497
|
+
async function recordManagedSkill(entry) {
|
|
498
|
+
const registry = await readManagedSkillRegistry();
|
|
499
|
+
const existing = registry.skills.findIndex((skill) => skill.path === entry.path);
|
|
500
|
+
const next = {
|
|
501
|
+
...entry,
|
|
502
|
+
updatedAt: new Date().toISOString(),
|
|
503
|
+
};
|
|
504
|
+
if (existing >= 0) {
|
|
505
|
+
registry.skills[existing] = next;
|
|
506
|
+
}
|
|
507
|
+
else {
|
|
508
|
+
registry.skills.push(next);
|
|
509
|
+
}
|
|
510
|
+
const registryPath = getManagedSkillRegistryPath();
|
|
511
|
+
await mkdir(dirname(registryPath), { recursive: true });
|
|
512
|
+
await writeFile(registryPath, `${JSON.stringify(registry, null, 2)}\n`, { mode: 0o644 });
|
|
513
|
+
}
|
|
514
|
+
async function readManagedSkillRegistry() {
|
|
515
|
+
try {
|
|
516
|
+
const raw = await readFile(getManagedSkillRegistryPath(), 'utf8');
|
|
517
|
+
const parsed = JSON.parse(raw);
|
|
518
|
+
if (parsed.version !== 1 || !Array.isArray(parsed.skills)) {
|
|
519
|
+
return { version: 1, skills: [] };
|
|
520
|
+
}
|
|
521
|
+
return {
|
|
522
|
+
version: 1,
|
|
523
|
+
skills: parsed.skills.filter((skill) => {
|
|
524
|
+
return Boolean(skill)
|
|
525
|
+
&& isSkillName(skill.skill)
|
|
526
|
+
&& typeof skill.path === 'string'
|
|
527
|
+
&& typeof skill.template === 'string'
|
|
528
|
+
&& typeof skill.templateHash === 'string';
|
|
529
|
+
}),
|
|
530
|
+
};
|
|
531
|
+
}
|
|
532
|
+
catch (error) {
|
|
533
|
+
if (isMissingFileError(error))
|
|
534
|
+
return { version: 1, skills: [] };
|
|
535
|
+
throw error;
|
|
536
|
+
}
|
|
537
|
+
}
|
|
538
|
+
function sha256(value) {
|
|
539
|
+
return createHash('sha256').update(value).digest('hex');
|
|
540
|
+
}
|
|
541
|
+
function getManagedSkillRegistryPath() {
|
|
542
|
+
return process.env.COAUTHOR_MANAGED_SKILLS_REGISTRY
|
|
543
|
+
? resolve(process.env.COAUTHOR_MANAGED_SKILLS_REGISTRY)
|
|
544
|
+
: join(homedir(), '.config', 'coauthor', 'managed-skills.json');
|
|
545
|
+
}
|
|
473
546
|
async function fileExists(path) {
|
|
474
547
|
try {
|
|
475
548
|
await readFile(path);
|
|
@@ -848,6 +921,7 @@ export function helpResult() {
|
|
|
848
921
|
' operation list|show|status',
|
|
849
922
|
' credits',
|
|
850
923
|
' skills list|install',
|
|
924
|
+
' skills install supports codex|claude|cursor|agents|all',
|
|
851
925
|
].join('\n'),
|
|
852
926
|
};
|
|
853
927
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@clickminded/coauthor-cli",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.9",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"bin": {
|
|
6
6
|
"coauthor": "dist/index.js",
|
|
@@ -19,11 +19,13 @@
|
|
|
19
19
|
},
|
|
20
20
|
"files": [
|
|
21
21
|
"dist",
|
|
22
|
+
"scripts",
|
|
22
23
|
"skills",
|
|
23
24
|
"README.md"
|
|
24
25
|
],
|
|
25
26
|
"scripts": {
|
|
26
27
|
"build": "tsc",
|
|
28
|
+
"postinstall": "node scripts/postinstall.mjs",
|
|
27
29
|
"test": "node --import tsx --test test/*.test.ts",
|
|
28
30
|
"typecheck": "tsc --noEmit"
|
|
29
31
|
},
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
import { createHash } from 'node:crypto'
|
|
2
|
+
import { mkdir, readFile, writeFile } from 'node:fs/promises'
|
|
3
|
+
import { dirname, join } from 'node:path'
|
|
4
|
+
import { fileURLToPath } from 'node:url'
|
|
5
|
+
import { homedir } from 'node:os'
|
|
6
|
+
|
|
7
|
+
const packageRoot = fileURLToPath(new URL('..', import.meta.url))
|
|
8
|
+
const registryPath = join(homedir(), '.config', 'coauthor', 'managed-skills.json')
|
|
9
|
+
|
|
10
|
+
async function main() {
|
|
11
|
+
const registry = await readRegistry()
|
|
12
|
+
if (registry.skills.length === 0) return
|
|
13
|
+
|
|
14
|
+
let changed = false
|
|
15
|
+
const nextSkills = []
|
|
16
|
+
for (const skill of registry.skills) {
|
|
17
|
+
const templatePath = resolveTemplatePath(skill.template)
|
|
18
|
+
if (!templatePath) {
|
|
19
|
+
nextSkills.push(skill)
|
|
20
|
+
continue
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
const template = await readFile(templatePath, 'utf8').catch(() => null)
|
|
24
|
+
if (template === null) {
|
|
25
|
+
nextSkills.push(skill)
|
|
26
|
+
continue
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
const current = await readFile(skill.path, 'utf8').catch((error) => {
|
|
30
|
+
return error && error.code === 'ENOENT' ? '' : null
|
|
31
|
+
})
|
|
32
|
+
if (current === null) {
|
|
33
|
+
nextSkills.push(skill)
|
|
34
|
+
continue
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
const currentHash = sha256(current)
|
|
38
|
+
const nextHash = sha256(template)
|
|
39
|
+
const safeToUpdate = current === '' || currentHash === skill.templateHash || currentHash === nextHash
|
|
40
|
+
if (!safeToUpdate) {
|
|
41
|
+
nextSkills.push(skill)
|
|
42
|
+
continue
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
if (currentHash !== nextHash) {
|
|
46
|
+
await mkdir(dirname(skill.path), { recursive: true })
|
|
47
|
+
await writeFile(skill.path, template, { mode: 0o644 })
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
nextSkills.push({
|
|
51
|
+
...skill,
|
|
52
|
+
templateHash: nextHash,
|
|
53
|
+
updatedAt: new Date().toISOString(),
|
|
54
|
+
})
|
|
55
|
+
changed = true
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
if (changed) {
|
|
59
|
+
await mkdir(dirname(registryPath), { recursive: true })
|
|
60
|
+
await writeFile(registryPath, `${JSON.stringify({ version: 1, skills: nextSkills }, null, 2)}\n`, { mode: 0o644 })
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
async function readRegistry() {
|
|
65
|
+
try {
|
|
66
|
+
const raw = await readFile(registryPath, 'utf8')
|
|
67
|
+
const parsed = JSON.parse(raw)
|
|
68
|
+
if (parsed?.version !== 1 || !Array.isArray(parsed.skills)) return { version: 1, skills: [] }
|
|
69
|
+
return {
|
|
70
|
+
version: 1,
|
|
71
|
+
skills: parsed.skills.filter((skill) => {
|
|
72
|
+
return skill
|
|
73
|
+
&& typeof skill.skill === 'string'
|
|
74
|
+
&& typeof skill.path === 'string'
|
|
75
|
+
&& typeof skill.template === 'string'
|
|
76
|
+
&& typeof skill.templateHash === 'string'
|
|
77
|
+
}),
|
|
78
|
+
}
|
|
79
|
+
} catch (error) {
|
|
80
|
+
if (error && error.code === 'ENOENT') return { version: 1, skills: [] }
|
|
81
|
+
throw error
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
function resolveTemplatePath(template) {
|
|
86
|
+
if (!template.startsWith('../skills/')) return null
|
|
87
|
+
return join(packageRoot, template.replace(/^\.\.\//, ''))
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
function sha256(value) {
|
|
91
|
+
return createHash('sha256').update(value).digest('hex')
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
main().catch((error) => {
|
|
95
|
+
console.warn(`[coauthor] skipped managed skill auto-update: ${error instanceof Error ? error.message : String(error)}`)
|
|
96
|
+
})
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: coauthor
|
|
3
|
+
description: Use the CoAuthor Agent CLI for project/workflow operations instead of browser routes, curl, or direct database access. Applies when inspecting or advancing CoAuthor projects, operations, exports, publishing, tokens, or workflow status.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
This skill guides agent use of the CoAuthor CLI.
|
|
7
|
+
|
|
8
|
+
## CLI First
|
|
9
|
+
|
|
10
|
+
- Prefer `coauthor` CLI commands for CoAuthor project and workflow work.
|
|
11
|
+
- Do not drive browser routes, hand-written `curl`, or direct database edits when a CLI command covers the task.
|
|
12
|
+
- Use the configured production base URL by default. Do not point the CLI at `localhost` or start a local dev server unless the user explicitly asks to test local changes.
|
|
13
|
+
- For local development only, pass an explicit one-off override such as `--base-url http://localhost:3000` or `COAUTHOR_BASE_URL=http://localhost:3000`.
|
|
14
|
+
- Use `--json` for machine-readable output and parse fields from that output.
|
|
15
|
+
- Use `--wait` for commands that start asynchronous work when the user expects the operation to finish.
|
|
16
|
+
- Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` when the user explicitly wants a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
|
|
17
|
+
- Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
|
|
18
|
+
- Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
|
|
19
|
+
- If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
|
|
20
|
+
- Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
|
|
21
|
+
- After a timeout, interruption, network error, or unclear result, check operation status before retrying.
|
|
22
|
+
- `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
|
|
23
|
+
|
|
24
|
+
## Safety
|
|
25
|
+
|
|
26
|
+
- Never print access tokens, publish tokens, service-role keys, cookies, or authorization headers.
|
|
27
|
+
- Never ask the user to paste Anthropic, OpenAI, or Gemini provider API keys into chat or the terminal; key entry belongs in CoAuthor AI settings.
|
|
28
|
+
- Pass tokens through environment variables or secret-backed CLI options only; do not paste them into prompts, logs, or shell history.
|
|
29
|
+
- Treat publish/export operations as live side effects.
|
|
30
|
+
- Require explicit user intent before live publish/export.
|
|
31
|
+
- Include `--yes` only when the user has clearly approved the live publish/export action.
|
|
32
|
+
|
|
33
|
+
## Workflow
|
|
34
|
+
|
|
35
|
+
1. Identify the project, operation, or export target.
|
|
36
|
+
2. Run the relevant `coauthor` command with `--json`.
|
|
37
|
+
3. Add `--wait` when starting or advancing asynchronous work.
|
|
38
|
+
4. If anything is uncertain, query workflow/research/draft status and report the current state.
|
|
39
|
+
5. For live publish/export, confirm explicit user intent, then run with `--yes`.
|
|
40
|
+
|
|
41
|
+
## Chat Transcript
|
|
42
|
+
|
|
43
|
+
Use `coauthor chat show <project-id> --json` to retrieve the workspace chat transcript, especially after long chat responses that may be truncated in terminal capture.
|
|
44
|
+
|
|
45
|
+
When using `coauthor chat <project-id> --stage draft --json`, treat the returned text as a workspace chat response, not a saved draft document. The CLI returns `draft_saved: false` and `transcript_command` when applicable. Use `coauthor draft get <project-id> --format markdown --json` only for a saved generated draft.
|
|
46
|
+
|
|
47
|
+
## Draft Export
|
|
48
|
+
|
|
49
|
+
Use `coauthor draft get <project-id> --format markdown --json` when the user needs a finished draft in Markdown. Generated images are resolved into Markdown image URLs when available.
|
|
50
|
+
|
|
51
|
+
Use `coauthor draft get <project-id> --format html --json` when the user needs HTML with resolved image tags.
|
|
52
|
+
|
|
53
|
+
Use `coauthor draft get <project-id> --format text --json` when the user needs plain text with image URL references.
|
|
54
|
+
|
|
55
|
+
Use `coauthor draft get <project-id> --format json --json` or omit `--format` when the user needs the raw editor document JSON.
|
package/skills/claude/SKILL.md
CHANGED
|
@@ -15,8 +15,11 @@ This skill guides agent use of the CoAuthor CLI.
|
|
|
15
15
|
- Use `--wait` for commands that start asynchronous work when the user expects the operation to finish.
|
|
16
16
|
- Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` when the user explicitly wants a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
|
|
17
17
|
- Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
|
|
18
|
+
- Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
|
|
19
|
+
- If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
|
|
18
20
|
- Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
|
|
19
21
|
- After a timeout, interruption, network error, or unclear result, check operation status before retrying.
|
|
22
|
+
- `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
|
|
20
23
|
|
|
21
24
|
## Safety
|
|
22
25
|
|
|
@@ -32,9 +35,15 @@ This skill guides agent use of the CoAuthor CLI.
|
|
|
32
35
|
1. Identify the project, operation, or export target.
|
|
33
36
|
2. Run the relevant `coauthor` command with `--json`.
|
|
34
37
|
3. Add `--wait` when starting or advancing asynchronous work.
|
|
35
|
-
4. If anything is uncertain, query
|
|
38
|
+
4. If anything is uncertain, query workflow/research/draft status and report the current state.
|
|
36
39
|
5. For live publish/export, confirm explicit user intent, then run with `--yes`.
|
|
37
40
|
|
|
41
|
+
## Chat Transcript
|
|
42
|
+
|
|
43
|
+
Use `coauthor chat show <project-id> --json` to retrieve the workspace chat transcript, especially after long chat responses that may be truncated in terminal capture.
|
|
44
|
+
|
|
45
|
+
When using `coauthor chat <project-id> --stage draft --json`, treat the returned text as a workspace chat response, not a saved draft document. The CLI returns `draft_saved: false` and `transcript_command` when applicable. Use `coauthor draft get <project-id> --format markdown --json` only for a saved generated draft.
|
|
46
|
+
|
|
38
47
|
## Draft Export
|
|
39
48
|
|
|
40
49
|
Use `coauthor draft get <project-id> --format markdown --json` when the user needs a finished draft in Markdown. Generated images are resolved into Markdown image URLs when available.
|
package/skills/codex/SKILL.md
CHANGED
|
@@ -15,8 +15,11 @@ This skill guides agent use of the CoAuthor CLI.
|
|
|
15
15
|
- Use `--wait` for commands that start asynchronous work when the user expects the operation to finish.
|
|
16
16
|
- Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` when the user explicitly wants a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
|
|
17
17
|
- Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
|
|
18
|
+
- Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
|
|
19
|
+
- If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
|
|
18
20
|
- Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
|
|
19
21
|
- After a timeout, interruption, network error, or unclear result, check operation status before retrying.
|
|
22
|
+
- `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
|
|
20
23
|
|
|
21
24
|
## Safety
|
|
22
25
|
|
|
@@ -32,9 +35,15 @@ This skill guides agent use of the CoAuthor CLI.
|
|
|
32
35
|
1. Identify the project, operation, or export target.
|
|
33
36
|
2. Run the relevant `coauthor` command with `--json`.
|
|
34
37
|
3. Add `--wait` when starting or advancing asynchronous work.
|
|
35
|
-
4. If anything is uncertain, query
|
|
38
|
+
4. If anything is uncertain, query workflow/research/draft status and report the current state.
|
|
36
39
|
5. For live publish/export, confirm explicit user intent, then run with `--yes`.
|
|
37
40
|
|
|
41
|
+
## Chat Transcript
|
|
42
|
+
|
|
43
|
+
Use `coauthor chat show <project-id> --json` to retrieve the workspace chat transcript, especially after long chat responses that may be truncated in terminal capture.
|
|
44
|
+
|
|
45
|
+
When using `coauthor chat <project-id> --stage draft --json`, treat the returned text as a workspace chat response, not a saved draft document. The CLI returns `draft_saved: false` and `transcript_command` when applicable. Use `coauthor draft get <project-id> --format markdown --json` only for a saved generated draft.
|
|
46
|
+
|
|
38
47
|
## Draft Export
|
|
39
48
|
|
|
40
49
|
Use `coauthor draft get <project-id> --format markdown --json` when the user needs a finished draft in Markdown. Generated images are resolved into Markdown image URLs when available.
|
|
@@ -12,8 +12,11 @@ alwaysApply: true
|
|
|
12
12
|
- Use `--wait` when starting asynchronous work and the user expects a completed result.
|
|
13
13
|
- Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` for a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
|
|
14
14
|
- Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
|
|
15
|
+
- Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
|
|
16
|
+
- If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
|
|
15
17
|
- Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
|
|
16
18
|
- After timeout, interruption, network error, or ambiguous output, check operation status before retrying or reporting success.
|
|
19
|
+
- `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
|
|
17
20
|
- Never print tokens, service-role keys, cookies, or authorization headers.
|
|
18
21
|
- Never ask the user to paste Anthropic, OpenAI, or Gemini provider API keys into chat or the terminal; key entry belongs in CoAuthor AI settings.
|
|
19
22
|
- Pass tokens through environment variables or secret-backed CLI options only.
|
|
@@ -23,6 +26,8 @@ alwaysApply: true
|
|
|
23
26
|
|
|
24
27
|
## Draft Export
|
|
25
28
|
|
|
29
|
+
- Use `coauthor chat show <project-id> --json` to retrieve workspace chat transcripts after long chat responses.
|
|
30
|
+
- Treat `coauthor chat <project-id> --stage draft --json` as a workspace chat response, not a saved draft document. The CLI returns `draft_saved: false` and `transcript_command` when applicable.
|
|
26
31
|
- Use `coauthor draft get <project-id> --format markdown --json` for finished draft Markdown. Generated images resolve into Markdown image URLs when available.
|
|
27
32
|
- Use `coauthor draft get <project-id> --format html --json` for HTML with resolved image tags.
|
|
28
33
|
- Use `coauthor draft get <project-id> --format text --json` for plain text with image URL references.
|