@areca-cms/skills 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Areca CMS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# `@areca-cms/skills`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Agent skills that teach AI coding agents and chat apps how to work with Areca CMS:
+
+| Skill | Teaches |
+| --- | --- |
+| `areca-sdk` | Connecting a website with `@areca-cms/site-sdk`: tokens and env vars, `areca.config.ts`, the `areca` CLI, reading content, rich text, SEO, preview routes, Go-live builds |
+| `areca-mcp` | Connecting an AI to a site's MCP server and using it: OAuth and personal keys, roles, the draft/ready/live workflow, field formats, SEO, images, every tool |
+
+The skills are plain `SKILL.md` folders in the open [Agent Skills](https://agentskills.io) format. They have no scripts and no dependencies, so they work in any project.
+
+## Install
+
+```bash
+npx @areca-cms/skills
+```
+
+Pick your agents in the selector (agents found in the project are preselected), then choose the skills and project or user scope. You can optionally add the site's MCP connector URL as well. Only the URL is written, never a secret, and each agent signs in to Areca in the browser on first use.
+
+Non-interactive:
+
+```bash
+npx @areca-cms/skills add -a claude-code,codex,cursor -y
+npx @areca-cms/skills add -a claude-code --mcp-url https://cms.example.com/api/mcp/acme-site -y
+npx @areca-cms/skills add -a codex --global -y      # user-level folders
+npx @areca-cms/skills mcp -a cursor --url https://cms.example.com/api/mcp/acme-site
+npx @areca-cms/skills export --out ./zips           # Claude app / ChatGPT uploads
+npx @areca-cms/skills remove -a claude-code -y
+npx @areca-cms/skills list                          # agent ids and folders
+```
+
+Agents that share a folder get one copy. For example, Codex, Cursor, Copilot, Gemini CLI and OpenCode all read `.agents/skills`. Re-running `add` updates the skills in place, and `remove` deletes only `areca-*` folders.
+
+## Supported agents
+
+**Coding agents:** Claude Code, Codex, Cursor, GitHub Copilot, OpenCode, Gemini CLI, Windsurf, Antigravity, Cline, Roo Code, Kilo Code, Kiro, Amp, Factory Droid, Goose, JetBrains Junie, Continue, Augment, Zed, Trae, Warp, OpenHands, Qwen Code, plus any other agent that reads `.agents/skills`.
+
+**Chat apps:** the Claude app (web and desktop) and ChatGPT. Choosing one exports one `.zip` per skill:
+
+- Claude: Customize > Skills > + > Upload a skill (code execution must be on).
+- ChatGPT: Skills > Create > Upload from your computer.
+
+MCP config is written to the project file for Claude Code (`.mcp.json`), Cursor, VS Code and Copilot, Codex, OpenCode, Gemini CLI, Roo Code, Kiro, Factory, Junie, Continue and Qwen Code. Agents with only a user-level config or a settings UI get the snippet printed instead.
+
+## Other ways to install
+
+- **Claude Code plugin:** `/plugin marketplace add ekozf/areca-cms`, then `/plugin install areca@areca-cms`.
+- **skills CLI:** `npx skills add ekozf/areca-cms --skill areca-sdk --skill areca-mcp`.
+- **Manually:** copy `skills/areca-*` from the repository into your agent's skills folder.
+
+## Development
+
+The skill source lives in the repository root under `skills/`. The build copies it into this package. `pnpm test` checks the skills against the agentskills.io spec, and also checks that every SDK export, CLI command, env var and MCP tool in the monorepo is documented, and that no removed tool still is.
+
+Releases are automated; see [Releasing packages](../../docs/DEVELOPMENT.md#releasing-packages). The release PR bumps `version` here, in `.claude-plugin/plugin.json` and in each `SKILL.md` `metadata.version` together (the tests enforce that they match). Commits under `packages/skills/`, `skills/` and `.claude-plugin/` count towards a skills release.

package/dist/agents.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Where each agent reads Agent Skills (SKILL.md folders) and how it registers a
+ * remote MCP server. Project paths are relative to the repo; global paths are
+ * relative to the home directory. Agents that share `.agents/skills` dedupe to
+ * one copy on install.
+ */
+export type McpTarget = 
+/** Merge `{ [key]: { [name]: entry } }` into a JSON file in the project. */
+{
+    kind: 'json';
+    file: string;
+    key: string;
+    entry: (url: string) => Record<string, unknown>;
+}
+/** Append `[mcp_servers.<name>]` to a TOML file in the project. */
+ | {
+    kind: 'toml';
+    file: string;
+}
+/** Write a standalone YAML file per server in the project. */
+ | {
+    kind: 'yaml';
+    dir: string;
+}
+/** No project config: print where and what to add. */
+ | {
+    kind: 'manual';
+    where: string;
+    snippet: (name: string, url: string) => string;
+};
+export type AgentGroup = 'popular' | 'more' | 'chat';
+export type Agent = {
+    id: string;
+    label: string;
+    group: AgentGroup;
+    /** Project skills dir. Absent for chat apps (zip upload only). */
+    projectDir?: string;
+    /** User-level skills dir, relative to `~`. */
+    globalDir?: string;
+    /** Paths whose presence suggests the agent is used in this project. */
+    detect: string[];
+    /** MCP registration. Multiple entries when an agent reads several files. */
+    mcp: McpTarget[];
+    /** Shown after install, e.g. how to sign in to the MCP server. */
+    after?: string;
+};
+export declare const AGENTS: Agent[];
+export declare const GROUP_LABELS: Record<AgentGroup, string>;
+export declare function findAgent(id: string): Agent | undefined;
+/** `areca-<slug>` from a connector URL `…/api/mcp/<slug>`, matching the CMS install buttons. */
+export declare function mcpServerName(connectorUrl: string): string;
+/** Accepts `https://cms/api/mcp/<slug>` (or http on localhost). Returns an error message or undefined. */
+export declare function validateConnectorUrl(value: string): string | undefined;

package/dist/agents.js

@@ -0,0 +1,302 @@
+/**
+ * Where each agent reads Agent Skills (SKILL.md folders) and how it registers a
+ * remote MCP server. Project paths are relative to the repo; global paths are
+ * relative to the home directory. Agents that share `.agents/skills` dedupe to
+ * one copy on install.
+ */
+const json = (file, key, entry) => ({
+    kind: 'json',
+    file,
+    key,
+    entry,
+});
+const manual = (where, snippet) => ({
+    kind: 'manual',
+    where,
+    snippet,
+});
+const jsonSnippet = (key, entry) => (name) => JSON.stringify({ [key]: { [name]: entry } }, null, 2);
+const httpEntry = (url) => ({ type: 'http', url });
+const urlEntry = (url) => ({ url });
+const settingsUi = manual('the MCP settings screen', (name, url) => `Add a remote (Streamable HTTP) server named ${name} with URL ${url}`);
+export const AGENTS = [
+    {
+        id: 'claude-code',
+        label: 'Claude Code',
+        group: 'popular',
+        projectDir: '.claude/skills',
+        globalDir: '.claude/skills',
+        detect: ['.claude', 'CLAUDE.md', '.mcp.json'],
+        mcp: [json('.mcp.json', 'mcpServers', httpEntry)],
+        after: 'Claude Code: run /mcp, pick the Areca server and choose Authenticate.',
+    },
+    {
+        id: 'codex',
+        label: 'Codex (CLI, IDE, app)',
+        group: 'popular',
+        projectDir: '.agents/skills',
+        globalDir: '.agents/skills',
+        detect: ['.codex', 'AGENTS.md'],
+        mcp: [{ kind: 'toml', file: '.codex/config.toml' }],
+        after: 'Codex: run `codex mcp login <name>` (project config needs a trusted project).',
+    },
+    {
+        id: 'cursor',
+        label: 'Cursor',
+        group: 'popular',
+        projectDir: '.agents/skills',
+        globalDir: '.cursor/skills',
+        detect: ['.cursor', '.cursorrules'],
+        mcp: [json('.cursor/mcp.json', 'mcpServers', urlEntry)],
+        after: 'Cursor: enable the server in Settings > MCP and sign in when asked.',
+    },
+    {
+        id: 'github-copilot',
+        label: 'GitHub Copilot (VS Code, CLI)',
+        group: 'popular',
+        projectDir: '.agents/skills',
+        globalDir: '.copilot/skills',
+        detect: ['.github/copilot-instructions.md', '.github/skills', '.vscode/mcp.json'],
+        mcp: [json('.vscode/mcp.json', 'servers', httpEntry), json('.mcp.json', 'mcpServers', httpEntry)],
+        after: 'VS Code: start the server from .vscode/mcp.json and sign in when asked.',
+    },
+    {
+        id: 'opencode',
+        label: 'OpenCode',
+        group: 'popular',
+        projectDir: '.agents/skills',
+        globalDir: '.config/opencode/skills',
+        detect: ['opencode.json', 'opencode.jsonc', '.opencode'],
+        mcp: [json('opencode.json', 'mcp', (url) => ({ type: 'remote', url, enabled: true }))],
+        after: 'OpenCode: run `opencode mcp auth <name>`.',
+    },
+    {
+        id: 'gemini-cli',
+        label: 'Gemini CLI',
+        group: 'popular',
+        projectDir: '.agents/skills',
+        globalDir: '.gemini/skills',
+        detect: ['.gemini', 'GEMINI.md'],
+        mcp: [json('.gemini/settings.json', 'mcpServers', (url) => ({ httpUrl: url }))],
+        after: 'Gemini CLI: run `/mcp auth <name>`.',
+    },
+    {
+        id: 'windsurf',
+        label: 'Windsurf',
+        group: 'popular',
+        projectDir: '.windsurf/skills',
+        globalDir: '.codeium/windsurf/skills',
+        detect: ['.windsurf', '.windsurfrules'],
+        mcp: [
+            manual('~/.codeium/windsurf/mcp_config.json', (name, url) => jsonSnippet('mcpServers', { serverUrl: url })(name)),
+        ],
+    },
+    {
+        id: 'antigravity',
+        label: 'Antigravity (IDE, CLI)',
+        group: 'more',
+        projectDir: '.agents/skills',
+        globalDir: '.gemini/antigravity/skills',
+        detect: [],
+        mcp: [settingsUi],
+    },
+    {
+        id: 'cline',
+        label: 'Cline',
+        group: 'more',
+        projectDir: '.cline/skills',
+        globalDir: '.cline/skills',
+        detect: ['.cline', '.clinerules'],
+        mcp: [
+            manual('Cline > MCP Servers > Configure (cline_mcp_settings.json)', (name, url) => jsonSnippet('mcpServers', { type: 'streamableHttp', url })(name)),
+        ],
+    },
+    {
+        id: 'roo',
+        label: 'Roo Code',
+        group: 'more',
+        projectDir: '.roo/skills',
+        globalDir: '.roo/skills',
+        detect: ['.roo', '.roorules'],
+        mcp: [json('.roo/mcp.json', 'mcpServers', (url) => ({ type: 'streamable-http', url }))],
+    },
+    {
+        id: 'kilo',
+        label: 'Kilo Code',
+        group: 'more',
+        projectDir: '.agents/skills',
+        globalDir: '.kilo/skills',
+        detect: ['.kilocode'],
+        mcp: [settingsUi],
+    },
+    {
+        id: 'kiro',
+        label: 'Kiro',
+        group: 'more',
+        projectDir: '.kiro/skills',
+        globalDir: '.kiro/skills',
+        detect: ['.kiro'],
+        mcp: [json('.kiro/settings/mcp.json', 'mcpServers', urlEntry)],
+    },
+    {
+        id: 'amp',
+        label: 'Amp',
+        group: 'more',
+        projectDir: '.agents/skills',
+        globalDir: '.config/agents/skills',
+        detect: ['.amp'],
+        mcp: [
+            manual('.amp/settings.json or your Amp user settings', (name, url) => jsonSnippet('amp.mcpServers', { url })(name)),
+        ],
+    },
+    {
+        id: 'factory',
+        label: 'Factory Droid',
+        group: 'more',
+        projectDir: '.factory/skills',
+        globalDir: '.factory/skills',
+        detect: ['.factory'],
+        mcp: [json('.factory/mcp.json', 'mcpServers', httpEntry)],
+    },
+    {
+        id: 'goose',
+        label: 'Goose',
+        group: 'more',
+        projectDir: '.agents/skills',
+        globalDir: '.agents/skills',
+        detect: ['.goosehints'],
+        mcp: [
+            manual('~/.config/goose/config.yaml', (name, url) => `extensions:\n  ${name}:\n    name: ${name}\n    type: streamable_http\n    uri: ${url}\n    enabled: true`),
+        ],
+    },
+    {
+        id: 'junie',
+        label: 'JetBrains Junie',
+        group: 'more',
+        projectDir: '.junie/skills',
+        globalDir: '.junie/skills',
+        detect: ['.junie'],
+        mcp: [json('.junie/mcp/mcp.json', 'mcpServers', urlEntry)],
+    },
+    {
+        id: 'continue',
+        label: 'Continue',
+        group: 'more',
+        projectDir: '.continue/skills',
+        globalDir: '.continue/skills',
+        detect: ['.continue'],
+        mcp: [{ kind: 'yaml', dir: '.continue/mcpServers' }],
+    },
+    {
+        id: 'augment',
+        label: 'Augment (Auggie)',
+        group: 'more',
+        projectDir: '.augment/skills',
+        globalDir: '.augment/skills',
+        detect: ['.augment', '.augment-guidelines'],
+        mcp: [manual('~/.augment/settings.json', (name, url) => jsonSnippet('mcpServers', httpEntry(url))(name))],
+    },
+    {
+        id: 'zed',
+        label: 'Zed',
+        group: 'more',
+        projectDir: '.agents/skills',
+        globalDir: '.agents/skills',
+        detect: ['.zed', '.rules'],
+        mcp: [manual('~/.config/zed/settings.json', (name, url) => jsonSnippet('context_servers', { url })(name))],
+    },
+    {
+        id: 'trae',
+        label: 'Trae',
+        group: 'more',
+        projectDir: '.trae/skills',
+        globalDir: '.trae/skills',
+        detect: ['.trae'],
+        mcp: [settingsUi],
+    },
+    {
+        id: 'warp',
+        label: 'Warp',
+        group: 'more',
+        projectDir: '.agents/skills',
+        globalDir: '.agents/skills',
+        detect: ['WARP.md'],
+        mcp: [settingsUi],
+    },
+    {
+        id: 'openhands',
+        label: 'OpenHands',
+        group: 'more',
+        projectDir: '.openhands/skills',
+        globalDir: '.openhands/skills',
+        detect: ['.openhands'],
+        mcp: [settingsUi],
+    },
+    {
+        id: 'qwen-code',
+        label: 'Qwen Code',
+        group: 'more',
+        projectDir: '.qwen/skills',
+        globalDir: '.qwen/skills',
+        detect: ['.qwen', 'QWEN.md'],
+        mcp: [json('.qwen/settings.json', 'mcpServers', (url) => ({ httpUrl: url }))],
+    },
+    {
+        id: 'universal',
+        label: 'Other / generic agent (.agents/skills)',
+        group: 'more',
+        projectDir: '.agents/skills',
+        globalDir: '.agents/skills',
+        detect: [],
+        mcp: [manual('your agent\'s MCP config', (name, url) => jsonSnippet('mcpServers', { url })(name))],
+    },
+    {
+        id: 'claude-app',
+        label: 'Claude app (web, desktop)',
+        group: 'chat',
+        detect: [],
+        mcp: [],
+        after: 'Claude app: Customize > Skills > + > Upload a skill, once per zip (needs "Code execution" on). Connect the MCP under Customize > Connectors > Add custom connector.',
+    },
+    {
+        id: 'chatgpt',
+        label: 'ChatGPT',
+        group: 'chat',
+        detect: [],
+        mcp: [],
+        after: 'ChatGPT: Skills > Create > Upload from your computer, once per zip (workspace admins may need to allow skill uploads). Connect the MCP under Settings > Apps > Create (Developer mode).',
+    },
+];
+export const GROUP_LABELS = {
+    popular: 'Popular coding agents',
+    more: 'More coding agents',
+    chat: 'Chat apps (exports .zip to upload)',
+};
+export function findAgent(id) {
+    return AGENTS.find((agent) => agent.id === id);
+}
+/** `areca-<slug>` from a connector URL `…/api/mcp/<slug>`, matching the CMS install buttons. */
+export function mcpServerName(connectorUrl) {
+    const slug = new URL(connectorUrl).pathname.split('/').filter(Boolean).at(-1) ?? '';
+    const clean = slug
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return `areca-${clean || 'site'}`;
+}
+/** Accepts `https://cms/api/mcp/<slug>` (or http on localhost). Returns an error message or undefined. */
+export function validateConnectorUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return 'Enter a full URL, e.g. https://cms.example.com/api/mcp/acme-site';
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:')
+        return 'Use an http(s) URL';
+    if (!/\/api\/mcp\/[^/]+\/?$/.test(url.pathname)) {
+        return 'Use the connector URL from Connect AI: <cms>/api/mcp/<site-slug>';
+    }
+    return undefined;
+}

package/dist/cli.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+export declare function run(argv: string[], cwd?: string): Promise<number>;
+/** `${ARECA_CMS_URL}/api/mcp/${siteKey}` from the site project, if both are present. */
+export declare function guessConnectorUrl(cwd: string): string | undefined;