@timelesscms-com/mcp-server 0.1.0

package/dist/tools/pages.js

@@ -0,0 +1,206 @@
+// Pages tools. Read + write + batch + blocks-view + preview.
+import { z } from 'zod';
+import { ok, withErrorBoundary, versionParam } from './helpers.js';
+function v(version) {
+    return version ? { version } : undefined;
+}
+export const pageTools = [
+    {
+        name: 'list_pages',
+        description: 'List pages on the active site. Returns id, title, slug, status, and SEO summary. Supports filtering by status and forward-cursor pagination.',
+        inputSchema: {
+            status: z.enum(['draft', 'review', 'unlisted', 'published', 'all']).optional(),
+            limit: z.number().int().min(1).max(200).optional(),
+            cursor: z.string().optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, 'pages', {
+                status: args.status,
+                limit: args.limit,
+                cursor: args.cursor,
+                ...v(args.version),
+            });
+            return ok(res);
+        }),
+    },
+    {
+        name: 'read_page',
+        description: 'Fetch one page in full — title, slug, status, html_content, SEO fields.',
+        inputSchema: {
+            page_id: z.string(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `pages/${encodeURIComponent(args.page_id)}`, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'batch_read_pages',
+        description: 'Read up to 200 pages in a single call. Use to bulk-load context before a redesign sweep.',
+        inputSchema: {
+            page_ids: z.array(z.string()).min(1).max(200),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, 'pages/batch-read', { page_ids: args.page_ids }, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'create_page',
+        description: 'Create a new HTML-mode page. Slug is derived from title if omitted; default status is "draft". Returns the created page.',
+        inputSchema: {
+            title: z.string().min(1),
+            slug: z.string().optional(),
+            html_content: z.string().optional(),
+            status: z.enum(['draft', 'review', 'unlisted', 'published']).optional(),
+            seo_title: z.string().optional(),
+            seo_description: z.string().optional(),
+            kind: z.enum(['page', 'article']).optional(),
+            author: z.string().optional(),
+            language: z.string().optional().describe('BCP-47 tag overriding the site default (e.g. "en" on an otherwise Swedish site).'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { version, ...body } = args;
+            const res = await client.post(siteId, 'pages', body, v(version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'update_page',
+        description: 'Shallow-merge update on a page (only the fields you pass change). Returns the updated page. For "replace this page entirely", use replace_page instead.',
+        inputSchema: {
+            page_id: z.string(),
+            patch: z
+                .object({
+                title: z.string().optional(),
+                slug: z.string().optional(),
+                html_content: z.string().optional(),
+                status: z.enum(['draft', 'review', 'unlisted', 'published']).optional(),
+                kind: z.enum(['page', 'article']).optional(),
+                author: z.string().optional(),
+                language: z.string().optional(),
+                seo_title: z.string().optional(),
+                seo_description: z.string().optional(),
+                og_image: z.string().optional(),
+                canonical_url: z.string().optional(),
+                noindex: z.boolean().optional(),
+                json_ld: z.string().optional(),
+                template: z.string().optional(),
+            })
+                .passthrough(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.patch(siteId, `pages/${encodeURIComponent(args.page_id)}`, args.patch, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'replace_page',
+        description: 'Full replace of a page\'s writable fields (PUT). Omitted fields are reset to undefined; use update_page if you want shallow merge.',
+        inputSchema: {
+            page_id: z.string(),
+            page: z.object({ title: z.string().min(1) }).passthrough(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.put(siteId, `pages/${encodeURIComponent(args.page_id)}`, args.page, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'batch_update_pages',
+        description: 'Apply per-page patches in one call (up to 200 entries). Each entry is { page_id, patch }; failures are reported per-row, the rest still apply.',
+        inputSchema: {
+            updates: z
+                .array(z.object({
+                page_id: z.string(),
+                patch: z.record(z.unknown()),
+            }))
+                .min(1)
+                .max(200),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, 'pages/batch-write', args.updates, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'clone_page',
+        description: 'Duplicate an existing page under a new title + slug. Use this when you want a near-copy of an existing page as the starting point (e.g. duplicate "Privatflytt" → "Privatflytt Härnösand"). The new page is created as a draft regardless of the source\'s status. Returns the created page.',
+        inputSchema: {
+            source_page_id: z.string(),
+            title: z.string().min(1).describe('Title for the new page.'),
+            slug: z.string().optional().describe('Slug for the new page. Omit to auto-derive from title.'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            // 1. Read the source — full body + SEO fields.
+            const sourceRes = await client.get(siteId, `pages/${encodeURIComponent(args.source_page_id)}`, v(args.version));
+            const src = sourceRes.page;
+            // 2. Build the new page body. Title + slug from args, everything else
+            //    copied — except the new page always starts as a draft so cloning
+            //    a published page doesn't accidentally publish a half-edited copy.
+            const body = {
+                title: args.title,
+                html_content: src.html_content,
+                seo_title: src.seo_title,
+                seo_description: src.seo_description,
+                og_image: src.og_image,
+                canonical_url: undefined, // intentionally NOT copied — point of canonical is to differ
+                noindex: src.noindex,
+                kind: src.kind,
+                author: src.author,
+                json_ld: undefined, // structured data is usually page-specific; force re-author
+                template: src.template,
+                status: 'draft',
+            };
+            if (args.slug)
+                body.slug = args.slug;
+            // 3. Create. The server auto-uniques the slug if it clashes.
+            const created = await client.post(siteId, 'pages', body, v(args.version));
+            return ok(created);
+        }),
+    },
+    {
+        name: 'delete_page',
+        description: 'Delete a page (tombstoned on branches, removed on main).',
+        inputSchema: {
+            page_id: z.string(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.del(siteId, `pages/${encodeURIComponent(args.page_id)}`, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'get_page_blocks',
+        description: 'Get the block hierarchy for a page. For today\'s HTML-mode pages returns { content_mode: "html", html_content }; once the block editor lands, block-mode pages return { content_mode: "blocks", blocks: [...] }.',
+        inputSchema: {
+            page_id: z.string(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `pages/${encodeURIComponent(args.page_id)}/blocks`, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'get_page_preview',
+        description: 'Get rendered HTML for one page (header-authed read). Returns { rendered_html, internal_links[] }. For a clickable preview URL use get_preview_link instead.',
+        inputSchema: {
+            page_id: z.string(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `pages/${encodeURIComponent(args.page_id)}/preview`, v(args.version));
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/partials.js

@@ -0,0 +1,108 @@
+// Partials (global blocks) tools.
+import { z } from 'zod';
+import { ok, withErrorBoundary, versionParam } from './helpers.js';
+function v(version) {
+    return version ? { version } : undefined;
+}
+export const partialTools = [
+    {
+        name: 'list_partials',
+        description: 'List global blocks (header, footer, free blocks). Defaults to summary mode (no html_content, just metadata + byte count) to keep agent context lean — pass include_content: true if you actually want the bodies inline, otherwise call read_partial on the one you care about.',
+        inputSchema: {
+            include_content: z.boolean().optional().describe('Include full html_content in the response. Default false.'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, 'partials', {
+                ...(args.include_content ? {} : { summary: 'true' }),
+                ...v(args.version),
+            });
+            return ok(res);
+        }),
+    },
+    {
+        name: 'read_partial',
+        description: 'Fetch one global block including its full HTML content.',
+        inputSchema: {
+            partial_id: z.string(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `partials/${encodeURIComponent(args.partial_id)}`, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'update_partial',
+        description: 'Shallow-merge update on a global block. Use partial_id "header" or "footer" for the auto-injected layout blocks, or a kebab-case id for a free block. HTML is sanitized server-side.',
+        inputSchema: {
+            partial_id: z.string(),
+            patch: z
+                .object({
+                name: z.string().optional(),
+                html_content: z.string().optional(),
+                status: z.enum(['draft', 'published']).optional(),
+                kind: z.enum(['header', 'footer', 'free']).optional(),
+            })
+                .passthrough(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.patch(siteId, `partials/${encodeURIComponent(args.partial_id)}`, args.patch, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'replace_partial',
+        description: 'Full replace of a global block (PUT). Use this when you want to set every field including auto-inferring kind from id.',
+        inputSchema: {
+            partial_id: z.string(),
+            partial: z.object({ html_content: z.string() }).passthrough(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.put(siteId, `partials/${encodeURIComponent(args.partial_id)}`, args.partial, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'create_free_block',
+        description: 'Create a new free (reusable) global block. Use a kebab-case id and embed it on pages with <x-include name="block-id" />.',
+        inputSchema: {
+            id: z.string().regex(/^[a-z0-9][a-z0-9-]{0,63}$/),
+            name: z.string().optional(),
+            html_content: z.string(),
+            status: z.enum(['draft', 'published']).optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { version, ...body } = args;
+            const res = await client.post(siteId, 'partials', body, v(version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'delete_partial',
+        description: 'Delete a free global block. header and footer cannot be deleted (they are layout blocks).',
+        inputSchema: {
+            partial_id: z.string(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.del(siteId, `partials/${encodeURIComponent(args.partial_id)}`, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'find_pages_using_block',
+        description: 'Pages that embed a given block via <x-include name="…">. For partial_id "header" or "footer" returns the full page list (they are auto-injected on every page). Use this to know the blast radius before editing a shared block.',
+        inputSchema: {
+            partial_id: z.string(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `partials/${encodeURIComponent(args.partial_id)}/usage`, v(args.version));
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/preview.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { ok, withErrorBoundary, versionParam } from './helpers.js';
+function v(version) {
+    return version ? { version } : undefined;
+}
+export const previewTools = [
+    {
+        name: 'get_preview_link',
+        description: 'Mint a short-lived signed URL the user (or your own browser tool) can open to SEE the rendered preview. Internal links inside the preview keep the same token attached, so the agent can navigate the whole site from one mint. Default TTL 15 min, max 24h. Target the preview at a page (page_id), a collection item (collection_name + item_id, resolves via route_template), or a raw slug. Omit all to land on the home page.',
+        inputSchema: {
+            page_id: z.string().optional(),
+            slug: z.string().optional(),
+            collection_name: z.string().optional(),
+            item_id: z.string().optional(),
+            ttl_seconds: z.number().int().min(60).max(86_400).optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { version, ...body } = args;
+            const res = await client.post(siteId, 'preview-link', body, v(version));
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/redirects.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { ok, withErrorBoundary, versionParam } from './helpers.js';
+function v(version) {
+    return version ? { version } : undefined;
+}
+export const redirectTools = [
+    {
+        name: 'list_redirects',
+        description: 'List redirect rules (from_path → to_path, status code).',
+        inputSchema: { version: versionParam },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, 'redirects', v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'create_redirect',
+        description: 'Create a redirect rule. Defaults to 301; pass status_code=302 for a temporary redirect.',
+        inputSchema: {
+            from_path: z.string().describe('Old path, leading slash (e.g. "/old-about")'),
+            to_path: z.string().describe('Target path or absolute URL'),
+            status_code: z.union([z.literal(301), z.literal(302)]).optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { version, ...body } = args;
+            const res = await client.post(siteId, 'redirects', body, v(version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'delete_redirect',
+        description: 'Remove a redirect rule.',
+        inputSchema: { redirect_id: z.string(), version: versionParam },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.del(siteId, `redirects/${encodeURIComponent(args.redirect_id)}`, v(args.version));
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/search.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { ok, withErrorBoundary, versionParam } from './helpers.js';
+function v(version) {
+    return version ? { version } : undefined;
+}
+export const searchTools = [
+    {
+        name: 'search_pages',
+        description: 'Search page bodies by literal substring or regex. Returns up to 500 matches each with an excerpt around the first hit. Use this to scope a redesign or a bulk replacement before running it.',
+        inputSchema: {
+            contains: z.string().optional().describe('Case-insensitive literal substring'),
+            regex: z.string().optional().describe('JS regex source (without slashes), case-insensitive'),
+            limit: z.number().int().min(1).max(500).optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { version, ...query } = args;
+            const res = await client.get(siteId, 'search', { ...query, ...v(version) });
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/settings.js

@@ -0,0 +1,56 @@
+// Settings tools. scripts_head, scripts_body_end, and custom_css are NOT
+// exposed — the server omits them on read and silently drops them on
+// write. Customers edit those manually in /app/sites/{id}/settings.
+import { z } from 'zod';
+import { ok, withErrorBoundary } from './helpers.js';
+export const settingsTools = [
+    {
+        name: 'read_site_settings',
+        description: 'Read the site\'s name, tagline, logo, favicon, colors, fonts, contact info, social links, default SEO suffix.',
+        handler: withErrorBoundary(async (_args, { client, siteId }) => {
+            const res = await client.get(siteId, 'settings');
+            return ok(res);
+        }),
+    },
+    {
+        name: 'update_site_settings',
+        description: 'Patch site settings. Only the fields you pass change. Nested objects (colors, fonts, contact, social) are shallow-merged. scripts_* and custom_css are not writable.',
+        inputSchema: {
+            site_name: z.string().optional(),
+            tagline: z.string().optional(),
+            logo: z.string().optional(),
+            favicon: z.string().optional(),
+            default_seo_suffix: z.string().optional(),
+            language: z.string().optional().describe('BCP-47 tag (e.g. "en", "sv", "en-GB"). Drives <html lang> on the rendered site.'),
+            robots_txt: z.string().optional(),
+            colors: z.record(z.string()).optional(),
+            fonts: z.record(z.unknown()).optional(),
+            contact: z
+                .object({
+                email: z.string().optional(),
+                phone: z.string().optional(),
+                // address can be a plain string (legacy) OR a structured
+                // PostalAddress for rich Schema.org JSON-LD.
+                address: z
+                    .union([
+                    z.string(),
+                    z.object({
+                        street_address: z.string().optional(),
+                        postal_code: z.string().optional(),
+                        address_locality: z.string().optional(),
+                        address_region: z.string().optional(),
+                        address_country: z.string().optional(),
+                    }).passthrough(),
+                ])
+                    .optional(),
+            })
+                .passthrough()
+                .optional(),
+            social: z.record(z.string()).optional(),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.patch(siteId, 'settings', args);
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/sites.js

@@ -0,0 +1,27 @@
+// Sites tools — discovery + Site-level identity edits.
+import { z } from 'zod';
+import { ok, withErrorBoundary } from './helpers.js';
+export const siteTools = [
+    {
+        name: 'get_site',
+        description: 'Read this site\'s metadata (id, name, slug, domain, active version) + a urls object covering the production / fallback / preview_base URLs. Useful as a first call to confirm the key is wired up and to learn what URLs the site is reachable at.',
+        handler: withErrorBoundary(async (_args, { client, siteId }) => {
+            const res = await client.get(siteId, '');
+            return ok(res);
+        }),
+    },
+    {
+        name: 'update_site',
+        description: 'Edit Site-level identity fields: name (display), slug (drives the {slug}.timelesscms-fallback subdomain — kebab-case, 3-48 chars, unique across the org), domain (the customer\'s real hostname; pass "" to clear). For colors / fonts / contact info / tagline use update_site_settings instead.',
+        inputSchema: {
+            name: z.string().min(1).optional(),
+            slug: z.string().optional().describe('Kebab-case identifier, 3-48 chars [a-z0-9-]. Empty string clears.'),
+            domain: z.string().optional().describe('Bare hostname e.g. "example.com". Empty string clears.'),
+            language: z.string().optional().describe('Default content language as a BCP-47 tag (e.g. "en", "sv", "en-GB"). Drives <html lang> and the default for alt-text generation. Empty string clears.'),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.patch(siteId, '', args);
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/versions.js

@@ -0,0 +1,52 @@
+// Version (branch) tools.
+import { z } from 'zod';
+import { ok, withErrorBoundary } from './helpers.js';
+export const versionTools = [
+    {
+        name: 'list_versions',
+        description: 'List versions (main + branches).',
+        handler: withErrorBoundary(async (_args, { client, siteId }) => {
+            const res = await client.get(siteId, 'versions');
+            return ok(res);
+        }),
+    },
+    {
+        name: 'create_branch',
+        description: 'Create a copy-on-write branch from main (or the version passed in `base`). New branches default to robots_blocked:true. Pass the new branch\'s id as ?version= on subsequent calls to read/write against it.',
+        inputSchema: {
+            name: z.string().min(1),
+            base: z.string().optional().describe('Source version id; defaults to main.'),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, 'versions', args);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'read_version',
+        description: 'Read one version\'s metadata.',
+        inputSchema: { version_id: z.string() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `versions/${encodeURIComponent(args.version_id)}`);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'delete_branch',
+        description: 'Discard a branch (main cannot be deleted).',
+        inputSchema: { version_id: z.string() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.del(siteId, `versions/${encodeURIComponent(args.version_id)}`);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'merge_branch',
+        description: 'Promote a branch\'s overrides + tombstones onto main. The branch is left in place so you can keep iterating; delete_branch removes it when you\'re done.',
+        inputSchema: { version_id: z.string() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, `versions/${encodeURIComponent(args.version_id)}/merge`);
+            return ok(res);
+        }),
+    },
+];

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@timelesscms-com/mcp-server",
+  "version": "0.1.0",
+  "description": "Model Context Protocol server for the TimelessCMS public API. Use with Claude Code or any MCP-compatible client to manage a TimelessCMS site.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "timelesscms-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "AGENTS.md",
+    "README.md",
+    "skills"
+  ],
+  "scripts": {
+    "build": "tsc -p .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.7"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mcp",
+    "timelesscms",
+    "claude",
+    "model-context-protocol"
+  ]
+}

package/skills/README.md

@@ -0,0 +1,63 @@
+# TimelessCMS skills for Claude Code
+
+Boilerplate skills that pair with [`@timelesscms-com/mcp-server`](../packages/mcp-server/README.md).
+Each one is a self-contained markdown file the agent reads when its
+description matches the user's request. Recipes call MCP tools; the agent
+adapts them to the specific job.
+
+## Installation
+
+Copy whichever skills you need into your Claude Code skills directory.
+Either:
+
+```bash
+# project-scoped (recommended)
+mkdir -p .claude/skills
+cp skills/*.md .claude/skills/
+
+# or user-scoped (available in every project)
+cp skills/*.md ~/.claude/skills/
+```
+
+Symlinks work too, so you can stay in sync with the upstream:
+
+```bash
+ln -s "$PWD/skills/tcms-migrate-wp.md" ~/.claude/skills/
+```
+
+## The skills
+
+| File | When it triggers | What it does |
+|---|---|---|
+| `tcms-migrate-wp.md`     | "migrate from WordPress", a wp-json URL is mentioned | Walks the WP REST, rebuilds each page in the target's design, transfers media, sets redirects, leaves everything as drafts for review |
+| `tcms-content-write.md`  | "write a page about…", "draft copy for…"            | Discovery first (settings + sample pages), then drafts in the site's voice, previews, iterates |
+| `tcms-images.md`         | "make an image / hero / illustration", media uploads | Generates locally → signed upload URL → metadata patch → embed |
+| `tcms-directory.md`      | Building a directory site, importing structured data | Schema → items → per-item URLs via `route_template` → listing page → preview → deploy |
+| `tcms-redesign-branch.md`| "redesign", "modernize", anything site-wide-design   | Branch-isolated work with preview links, merge when approved |
+
+## Prerequisites for every skill
+
+1. `@timelesscms-com/mcp-server` configured in `.claude.json` with a valid
+   `TCMS_API_KEY` and `TCMS_API_URL`.
+2. The agent has read `AGENTS.md` (ships with the MCP package — see
+   `node_modules/@timelesscms-com/mcp-server/AGENTS.md` after install, or
+   reference it directly).
+
+If those are missing, every skill will fail at the first MCP call with
+"Missing bearer token" or "Invalid or revoked token".
+
+## Authoring more
+
+Skills are markdown files that the agent loads on demand. Each one
+should include:
+
+- A `description:` frontmatter explaining when to load it (Claude uses
+  this to pick the right skill).
+- A clear set of preconditions (what MCP tools must work, what state the
+  agent needs to know).
+- A numbered recipe with concrete tool calls.
+- A "Pitfalls" section that captures lessons learned across customer
+  jobs.
+
+Keep them under ~150 lines so the agent reads them quickly. If a skill
+balloons, split it.