@contentrain/skills 0.1.2 → 0.2.1

package/README.md

@@ -5,92 +5,97 @@
 
 Workflow skills and framework guides for Contentrain-aware AI agents.
 
-This package is the procedural layer of the Contentrain ecosystem. It tells an agent how to apply the policy from `@contentrain/rules` in concrete tasks such as:
+This package follows the [Agent Skills standard](https://agentskills.io) for progressive disclosure: each skill has a `SKILL.md` (loaded on activation) and optional `references/` (loaded on demand).
 
-- initializing a project
-- creating content
-- running normalize
-- reviewing and submitting changes
-- generating the SDK client
-- translating content
-
-If `@contentrain/rules` defines constraints, `@contentrain/skills` defines execution playbooks.
-
-## 🚀 Install
+## Install
 
 ```bash
 pnpm add @contentrain/skills
 ```
 
-## 📦 What It Contains
+Or install directly via the skills CLI:
+
+```bash
+npx skills add contentrain/contentrain-ai --skill='*'
+```
 
-### Workflow skills
+## What It Contains
+
+### Agent Skills (standard format)
+
+Published under `skills/`:
+
+| Skill | Description |
+|-------|-------------|
+| `contentrain` | Core architecture, MCP tools, content formats |
+| `contentrain-normalize` | Two-phase normalize (extract + reuse) |
+| `contentrain-quality` | Content quality, SEO, accessibility, media |
+| `contentrain-sdk` | @contentrain/query SDK usage (local + CDN) |
+| `contentrain-content` | Content CRUD operations |
+| `contentrain-model` | Model creation/update |
+| `contentrain-init` | Project initialization |
+| `contentrain-bulk` | Batch operations |
+| `contentrain-validate-fix` | Validation and auto-fix |
+| `contentrain-review` | Content quality review |
+| `contentrain-translate` | Multi-locale translation |
+| `contentrain-generate` | SDK client generation |
+| `contentrain-serve` | Local review/normalize UI |
+| `contentrain-diff` | Branch content diffs |
+| `contentrain-doctor` | Project health diagnostics |
+
+Each skill directory contains:
+```
+skills/{name}/
+├── SKILL.md           # Instructions (< 500 lines)
+└── references/        # Detailed docs (loaded on demand)
+    └── *.md
+```
 
-Published under `workflows/*`:
+### Workflow skills (backward compat)
 
-- `contentrain-init.md`
-- `contentrain-model.md`
-- `contentrain-content.md`
-- `contentrain-bulk.md`
-- `contentrain-normalize.md`
-- `contentrain-validate-fix.md`
-- `contentrain-review.md`
-- `contentrain-diff.md`
-- `contentrain-doctor.md`
-- `contentrain-serve.md`
-- `contentrain-translate.md`
-- `contentrain-generate.md`
+Published under `workflows/*` — flat markdown files from previous versions. Still functional.
 
 ### Framework guides
 
 Published under `frameworks/*`:
 
-- `nuxt.md`
-- `next.md`
-- `astro.md`
-- `sveltekit.md`
-- `vue.md`
-- `react.md`
-- `expo.md`
-- `react-native.md`
-- `node.md`
-
-## 🧰 Public Exports
-
-The package root exports:
+- `nuxt.md`, `next.md`, `astro.md`, `sveltekit.md`, `vue.md`, `react.md`, `expo.md`, `react-native.md`, `node.md`
 
-- `WORKFLOW_SKILLS`
-- `FRAMEWORK_GUIDES`
-
-## 🧪 Example
+## Public Exports
 
 ```ts
-import { WORKFLOW_SKILLS, FRAMEWORK_GUIDES } from '@contentrain/skills'
+import { AGENT_SKILLS, WORKFLOW_SKILLS, FRAMEWORK_GUIDES } from '@contentrain/skills'
+
+// Agent Skills catalog (name + description for Tier 1 discovery)
+console.log(AGENT_SKILLS)
 
+// Backward compat
 console.log(WORKFLOW_SKILLS)
-console.log(FRAMEWORK_GUIDES.includes('next'))
+console.log(FRAMEWORK_GUIDES)
 ```
 
-## 🧠 Design Role
-
-`@contentrain/skills` is for step-by-step execution guidance:
+## Progressive Disclosure
 
-- `skills` = procedures and operational playbooks
-- `rules` = policy and non-negotiable constraints
+| Tier | What's Loaded | When | Token Cost |
+|------|--------------|------|------------|
+| 1. Catalog | `name` + `description` | Session start | ~50 tokens/skill |
+| 2. Instructions | Full `SKILL.md` body | Skill activated | < 5000 tokens |
+| 3. References | `references/*.md` | Agent needs detail | Varies |
 
-In practice:
+This reduces always-loaded context from ~4,700 lines to ~86 lines (essential guardrails only).
 
-- use `@contentrain/rules` to understand what is allowed
-- use `@contentrain/skills` to decide which workflow to run next
+## IDE Support
 
-## 🔗 Relationship To Other Packages
+Skills are installed by `contentrain init` for detected IDEs:
 
-- `@contentrain/mcp` provides the actual tool surface
-- `@contentrain/rules` defines policy and quality constraints
-- `contentrain` exposes CLI and serve workflows
-- `@contentrain/query` provides the generated content runtime
+| IDE | Rules Dir | Skills Dir |
+|-----|-----------|------------|
+| Claude Code | `.claude/rules/` | `.claude/skills/` |
+| Cursor | `.cursor/rules/` | `.cursor/skills/` |
+| Windsurf | `.windsurf/rules/` | `.windsurf/skills/` |
+| GitHub Copilot | `.github/` | `.agents/skills/` |
 
-## 🛠 Build
+## Build
 
 From the monorepo root:
 
@@ -100,6 +105,6 @@ pnpm --filter @contentrain/skills test
 pnpm --filter @contentrain/skills typecheck
 ```
 
-## 📄 License
+## License
 
 MIT

package/dist/index.cjs

@@ -3,8 +3,71 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 /**
 * @contentrain/skills — AI agent skills for Contentrain
 *
-* Step-by-step workflow procedures and framework integration guides.
+* Agent Skills standard format: SKILL.md + references/ for progressive disclosure.
+* Also includes workflow procedures and framework integration guides.
 */
+const AGENT_SKILLS = [
+	{
+		name: "contentrain",
+		description: "Contentrain CMS architecture, content formats, and MCP tool usage"
+	},
+	{
+		name: "contentrain-normalize",
+		description: "Two-phase normalize: extract hardcoded strings and patch source files"
+	},
+	{
+		name: "contentrain-quality",
+		description: "Content quality, SEO, accessibility, and media rules"
+	},
+	{
+		name: "contentrain-sdk",
+		description: "Query SDK usage: #contentrain imports, QueryBuilder, type-safe content access"
+	},
+	{
+		name: "contentrain-content",
+		description: "Create and manage content entries for existing models"
+	},
+	{
+		name: "contentrain-model",
+		description: "Design and save model definitions"
+	},
+	{
+		name: "contentrain-init",
+		description: "Initialize a new Contentrain project"
+	},
+	{
+		name: "contentrain-bulk",
+		description: "Batch operations on content entries"
+	},
+	{
+		name: "contentrain-validate-fix",
+		description: "Validate content and auto-fix structural issues"
+	},
+	{
+		name: "contentrain-review",
+		description: "Review content changes before publishing"
+	},
+	{
+		name: "contentrain-translate",
+		description: "Translate content across supported locales"
+	},
+	{
+		name: "contentrain-generate",
+		description: "Generate the typed SDK client from models"
+	},
+	{
+		name: "contentrain-serve",
+		description: "Start the local review and normalize UI"
+	},
+	{
+		name: "contentrain-diff",
+		description: "View content diffs between branches"
+	},
+	{
+		name: "contentrain-doctor",
+		description: "Diagnose project health issues"
+	}
+];
 const WORKFLOW_SKILLS = [
 	"contentrain-init",
 	"contentrain-model",
@@ -31,5 +94,6 @@ const FRAMEWORK_GUIDES = [
 	"node"
 ];
 //#endregion
+exports.AGENT_SKILLS = AGENT_SKILLS;
 exports.FRAMEWORK_GUIDES = FRAMEWORK_GUIDES;
 exports.WORKFLOW_SKILLS = WORKFLOW_SKILLS;

package/dist/index.d.cts

@@ -2,12 +2,60 @@
 /**
  * @contentrain/skills — AI agent skills for Contentrain
  *
- * Step-by-step workflow procedures and framework integration guides.
+ * Agent Skills standard format: SKILL.md + references/ for progressive disclosure.
+ * Also includes workflow procedures and framework integration guides.
  */
+declare const AGENT_SKILLS: readonly [{
+  readonly name: "contentrain";
+  readonly description: "Contentrain CMS architecture, content formats, and MCP tool usage";
+}, {
+  readonly name: "contentrain-normalize";
+  readonly description: "Two-phase normalize: extract hardcoded strings and patch source files";
+}, {
+  readonly name: "contentrain-quality";
+  readonly description: "Content quality, SEO, accessibility, and media rules";
+}, {
+  readonly name: "contentrain-sdk";
+  readonly description: "Query SDK usage: #contentrain imports, QueryBuilder, type-safe content access";
+}, {
+  readonly name: "contentrain-content";
+  readonly description: "Create and manage content entries for existing models";
+}, {
+  readonly name: "contentrain-model";
+  readonly description: "Design and save model definitions";
+}, {
+  readonly name: "contentrain-init";
+  readonly description: "Initialize a new Contentrain project";
+}, {
+  readonly name: "contentrain-bulk";
+  readonly description: "Batch operations on content entries";
+}, {
+  readonly name: "contentrain-validate-fix";
+  readonly description: "Validate content and auto-fix structural issues";
+}, {
+  readonly name: "contentrain-review";
+  readonly description: "Review content changes before publishing";
+}, {
+  readonly name: "contentrain-translate";
+  readonly description: "Translate content across supported locales";
+}, {
+  readonly name: "contentrain-generate";
+  readonly description: "Generate the typed SDK client from models";
+}, {
+  readonly name: "contentrain-serve";
+  readonly description: "Start the local review and normalize UI";
+}, {
+  readonly name: "contentrain-diff";
+  readonly description: "View content diffs between branches";
+}, {
+  readonly name: "contentrain-doctor";
+  readonly description: "Diagnose project health issues";
+}];
+type AgentSkillName = (typeof AGENT_SKILLS)[number]['name'];
 declare const WORKFLOW_SKILLS: readonly ["contentrain-init", "contentrain-model", "contentrain-content", "contentrain-bulk", "contentrain-normalize", "contentrain-validate-fix", "contentrain-review", "contentrain-diff", "contentrain-doctor", "contentrain-serve", "contentrain-translate", "contentrain-generate"];
 type WorkflowSkill = (typeof WORKFLOW_SKILLS)[number];
 declare const FRAMEWORK_GUIDES: readonly ["nuxt", "next", "astro", "sveltekit", "vue", "react", "expo", "react-native", "node"];
 type FrameworkGuide = (typeof FRAMEWORK_GUIDES)[number];
 //#endregion
-export { FRAMEWORK_GUIDES, FrameworkGuide, WORKFLOW_SKILLS, WorkflowSkill };
+export { AGENT_SKILLS, AgentSkillName, FRAMEWORK_GUIDES, FrameworkGuide, WORKFLOW_SKILLS, WorkflowSkill };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/index.ts"],"mappings":";;AAQA;;;;cAAa,eAAA;AAAA,KAeD,aAAA,WAAwB,eAAA;AAAA,cAIvB,gBAAA;AAAA,KACD,cAAA,WAAyB,gBAAA"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/index.ts"],"mappings":";;AASA;;;;;cAAa,YAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAkBD,cAAA,WAAyB,YAAA;AAAA,cAIxB,eAAA;AAAA,KAeD,aAAA,WAAwB,eAAA;AAAA,cAIvB,gBAAA;AAAA,KACD,cAAA,WAAyB,gBAAA"}

package/dist/index.d.mts

@@ -2,12 +2,60 @@
 /**
  * @contentrain/skills — AI agent skills for Contentrain
  *
- * Step-by-step workflow procedures and framework integration guides.
+ * Agent Skills standard format: SKILL.md + references/ for progressive disclosure.
+ * Also includes workflow procedures and framework integration guides.
  */
+declare const AGENT_SKILLS: readonly [{
+  readonly name: "contentrain";
+  readonly description: "Contentrain CMS architecture, content formats, and MCP tool usage";
+}, {
+  readonly name: "contentrain-normalize";
+  readonly description: "Two-phase normalize: extract hardcoded strings and patch source files";
+}, {
+  readonly name: "contentrain-quality";
+  readonly description: "Content quality, SEO, accessibility, and media rules";
+}, {
+  readonly name: "contentrain-sdk";
+  readonly description: "Query SDK usage: #contentrain imports, QueryBuilder, type-safe content access";
+}, {
+  readonly name: "contentrain-content";
+  readonly description: "Create and manage content entries for existing models";
+}, {
+  readonly name: "contentrain-model";
+  readonly description: "Design and save model definitions";
+}, {
+  readonly name: "contentrain-init";
+  readonly description: "Initialize a new Contentrain project";
+}, {
+  readonly name: "contentrain-bulk";
+  readonly description: "Batch operations on content entries";
+}, {
+  readonly name: "contentrain-validate-fix";
+  readonly description: "Validate content and auto-fix structural issues";
+}, {
+  readonly name: "contentrain-review";
+  readonly description: "Review content changes before publishing";
+}, {
+  readonly name: "contentrain-translate";
+  readonly description: "Translate content across supported locales";
+}, {
+  readonly name: "contentrain-generate";
+  readonly description: "Generate the typed SDK client from models";
+}, {
+  readonly name: "contentrain-serve";
+  readonly description: "Start the local review and normalize UI";
+}, {
+  readonly name: "contentrain-diff";
+  readonly description: "View content diffs between branches";
+}, {
+  readonly name: "contentrain-doctor";
+  readonly description: "Diagnose project health issues";
+}];
+type AgentSkillName = (typeof AGENT_SKILLS)[number]['name'];
 declare const WORKFLOW_SKILLS: readonly ["contentrain-init", "contentrain-model", "contentrain-content", "contentrain-bulk", "contentrain-normalize", "contentrain-validate-fix", "contentrain-review", "contentrain-diff", "contentrain-doctor", "contentrain-serve", "contentrain-translate", "contentrain-generate"];
 type WorkflowSkill = (typeof WORKFLOW_SKILLS)[number];
 declare const FRAMEWORK_GUIDES: readonly ["nuxt", "next", "astro", "sveltekit", "vue", "react", "expo", "react-native", "node"];
 type FrameworkGuide = (typeof FRAMEWORK_GUIDES)[number];
 //#endregion
-export { FRAMEWORK_GUIDES, FrameworkGuide, WORKFLOW_SKILLS, WorkflowSkill };
+export { AGENT_SKILLS, AgentSkillName, FRAMEWORK_GUIDES, FrameworkGuide, WORKFLOW_SKILLS, WorkflowSkill };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;AAQA;;;;cAAa,eAAA;AAAA,KAeD,aAAA,WAAwB,eAAA;AAAA,cAIvB,gBAAA;AAAA,KACD,cAAA,WAAyB,gBAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;AASA;;;;;cAAa,YAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAkBD,cAAA,WAAyB,YAAA;AAAA,cAIxB,eAAA;AAAA,KAeD,aAAA,WAAwB,eAAA;AAAA,cAIvB,gBAAA;AAAA,KACD,cAAA,WAAyB,gBAAA"}

package/dist/index.mjs

@@ -2,8 +2,71 @@
 /**
 * @contentrain/skills — AI agent skills for Contentrain
 *
-* Step-by-step workflow procedures and framework integration guides.
+* Agent Skills standard format: SKILL.md + references/ for progressive disclosure.
+* Also includes workflow procedures and framework integration guides.
 */
+const AGENT_SKILLS = [
+	{
+		name: "contentrain",
+		description: "Contentrain CMS architecture, content formats, and MCP tool usage"
+	},
+	{
+		name: "contentrain-normalize",
+		description: "Two-phase normalize: extract hardcoded strings and patch source files"
+	},
+	{
+		name: "contentrain-quality",
+		description: "Content quality, SEO, accessibility, and media rules"
+	},
+	{
+		name: "contentrain-sdk",
+		description: "Query SDK usage: #contentrain imports, QueryBuilder, type-safe content access"
+	},
+	{
+		name: "contentrain-content",
+		description: "Create and manage content entries for existing models"
+	},
+	{
+		name: "contentrain-model",
+		description: "Design and save model definitions"
+	},
+	{
+		name: "contentrain-init",
+		description: "Initialize a new Contentrain project"
+	},
+	{
+		name: "contentrain-bulk",
+		description: "Batch operations on content entries"
+	},
+	{
+		name: "contentrain-validate-fix",
+		description: "Validate content and auto-fix structural issues"
+	},
+	{
+		name: "contentrain-review",
+		description: "Review content changes before publishing"
+	},
+	{
+		name: "contentrain-translate",
+		description: "Translate content across supported locales"
+	},
+	{
+		name: "contentrain-generate",
+		description: "Generate the typed SDK client from models"
+	},
+	{
+		name: "contentrain-serve",
+		description: "Start the local review and normalize UI"
+	},
+	{
+		name: "contentrain-diff",
+		description: "View content diffs between branches"
+	},
+	{
+		name: "contentrain-doctor",
+		description: "Diagnose project health issues"
+	}
+];
 const WORKFLOW_SKILLS = [
 	"contentrain-init",
 	"contentrain-model",
@@ -30,6 +93,6 @@ const FRAMEWORK_GUIDES = [
 	"node"
 ];
 //#endregion
-export { FRAMEWORK_GUIDES, WORKFLOW_SKILLS };
+export { AGENT_SKILLS, FRAMEWORK_GUIDES, WORKFLOW_SKILLS };
 
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @contentrain/skills — AI agent skills for Contentrain\n *\n * Step-by-step workflow procedures and framework integration guides.\n */\n\n// ─── Workflow Skills ───\n\nexport const WORKFLOW_SKILLS = [\n  'contentrain-init',\n  'contentrain-model',\n  'contentrain-content',\n  'contentrain-bulk',\n  'contentrain-normalize',\n  'contentrain-validate-fix',\n  'contentrain-review',\n  'contentrain-diff',\n  'contentrain-doctor',\n  'contentrain-serve',\n  'contentrain-translate',\n  'contentrain-generate',\n] as const\n\nexport type WorkflowSkill = (typeof WORKFLOW_SKILLS)[number]\n\n// ─── Framework Guides ───\n\nexport const FRAMEWORK_GUIDES = ['nuxt', 'next', 'astro', 'sveltekit', 'vue', 'react', 'expo', 'react-native', 'node'] as const\nexport type FrameworkGuide = (typeof FRAMEWORK_GUIDES)[number]\n"],"mappings":";;;;;;AAQA,MAAa,kBAAkB;CAC7B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;AAMD,MAAa,mBAAmB;CAAC;CAAQ;CAAQ;CAAS;CAAa;CAAO;CAAS;CAAQ;CAAgB;CAAO"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @contentrain/skills — AI agent skills for Contentrain\n *\n * Agent Skills standard format: SKILL.md + references/ for progressive disclosure.\n * Also includes workflow procedures and framework integration guides.\n */\n\n// ─── Agent Skills Catalog ───\n\nexport const AGENT_SKILLS = [\n  { name: 'contentrain', description: 'Contentrain CMS architecture, content formats, and MCP tool usage' },\n  { name: 'contentrain-normalize', description: 'Two-phase normalize: extract hardcoded strings and patch source files' },\n  { name: 'contentrain-quality', description: 'Content quality, SEO, accessibility, and media rules' },\n  { name: 'contentrain-sdk', description: 'Query SDK usage: #contentrain imports, QueryBuilder, type-safe content access' },\n  { name: 'contentrain-content', description: 'Create and manage content entries for existing models' },\n  { name: 'contentrain-model', description: 'Design and save model definitions' },\n  { name: 'contentrain-init', description: 'Initialize a new Contentrain project' },\n  { name: 'contentrain-bulk', description: 'Batch operations on content entries' },\n  { name: 'contentrain-validate-fix', description: 'Validate content and auto-fix structural issues' },\n  { name: 'contentrain-review', description: 'Review content changes before publishing' },\n  { name: 'contentrain-translate', description: 'Translate content across supported locales' },\n  { name: 'contentrain-generate', description: 'Generate the typed SDK client from models' },\n  { name: 'contentrain-serve', description: 'Start the local review and normalize UI' },\n  { name: 'contentrain-diff', description: 'View content diffs between branches' },\n  { name: 'contentrain-doctor', description: 'Diagnose project health issues' },\n] as const\n\nexport type AgentSkillName = (typeof AGENT_SKILLS)[number]['name']\n\n// ─── Workflow Skills (backward compat) ───\n\nexport const WORKFLOW_SKILLS = [\n  'contentrain-init',\n  'contentrain-model',\n  'contentrain-content',\n  'contentrain-bulk',\n  'contentrain-normalize',\n  'contentrain-validate-fix',\n  'contentrain-review',\n  'contentrain-diff',\n  'contentrain-doctor',\n  'contentrain-serve',\n  'contentrain-translate',\n  'contentrain-generate',\n] as const\n\nexport type WorkflowSkill = (typeof WORKFLOW_SKILLS)[number]\n\n// ─── Framework Guides ───\n\nexport const FRAMEWORK_GUIDES = ['nuxt', 'next', 'astro', 'sveltekit', 'vue', 'react', 'expo', 'react-native', 'node'] as const\nexport type FrameworkGuide = (typeof FRAMEWORK_GUIDES)[number]\n"],"mappings":";;;;;;;AASA,MAAa,eAAe;CAC1B;EAAE,MAAM;EAAe,aAAa;EAAqE;CACzG;EAAE,MAAM;EAAyB,aAAa;EAAyE;CACvH;EAAE,MAAM;EAAuB,aAAa;EAAwD;CACpG;EAAE,MAAM;EAAmB,aAAa;EAAiF;CACzH;EAAE,MAAM;EAAuB,aAAa;EAAyD;CACrG;EAAE,MAAM;EAAqB,aAAa;EAAqC;CAC/E;EAAE,MAAM;EAAoB,aAAa;EAAwC;CACjF;EAAE,MAAM;EAAoB,aAAa;EAAuC;CAChF;EAAE,MAAM;EAA4B,aAAa;EAAmD;CACpG;EAAE,MAAM;EAAsB,aAAa;EAA4C;CACvF;EAAE,MAAM;EAAyB,aAAa;EAA8C;CAC5F;EAAE,MAAM;EAAwB,aAAa;EAA6C;CAC1F;EAAE,MAAM;EAAqB,aAAa;EAA2C;CACrF;EAAE,MAAM;EAAoB,aAAa;EAAuC;CAChF;EAAE,MAAM;EAAsB,aAAa;EAAkC;CAC9E;AAMD,MAAa,kBAAkB;CAC7B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;AAMD,MAAa,mBAAmB;CAAC;CAAQ;CAAQ;CAAS;CAAa;CAAO;CAAS;CAAQ;CAAgB;CAAO"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentrain/skills",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "license": "MIT",
   "description": "AI agent skills for Contentrain — workflow procedures, framework integration guides",
   "type": "module",
@@ -40,11 +40,13 @@
       "require": "./dist/index.cjs",
       "default": "./dist/index.mjs"
     },
+    "./skills/*": "./skills/*",
     "./workflows/*": "./workflows/*",
     "./frameworks/*": "./frameworks/*"
   },
   "files": [
     "dist",
+    "skills",
     "workflows",
     "frameworks"
   ],

package/skills/contentrain/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: contentrain
+description: "Contentrain CMS architecture, content formats, and MCP tool usage. Use when working with .contentrain/ directory, content models, or Contentrain MCP tools."
+metadata:
+  author: Contentrain
+  version: "1.0.0"
+---
+
+# Contentrain Skill
+
+Contentrain is a Git-based, AI-first content management system. Content lives in `.contentrain/` as JSON and Markdown files, managed through MCP tools. This skill covers architecture, content formats, and tool usage.
+
+## Architecture: Agent vs MCP
+
+The system separates **intelligence** (agent) from **infrastructure** (MCP tools).
+
+**Agent responsibilities:**
+- Analyze the project (tech stack, architecture, existing patterns)
+- Decide what constitutes content vs code
+- Assign domain grouping and model structure
+- Create replacement expressions (stack-aware: `{t('key')}` vs `{{ $t('key') }}`)
+- Make all semantic and content decisions
+
+**MCP responsibilities:**
+- Build project graph (import/component relationships)
+- Find string candidates (regex + filter)
+- Read/write/delete content and models
+- Patch source files (exact string replacement)
+- Validate against schema rules
+- Manage Git transactions (worktree, branch, commit, merge/push)
+
+**Rule:** MCP does NOT make content decisions. It provides reliable, framework-agnostic tooling.
+
+## Four Model Kinds
+
+| Kind | Storage | Use For |
+|------|---------|---------|
+| **Singleton** | JSON object, one file per locale | Page sections, site config, navigation |
+| **Collection** | Object-map by entry ID (sorted keys) | Team members, products, FAQs, categories |
+| **Document** | Markdown + YAML frontmatter | Blog posts, documentation, changelogs |
+| **Dictionary** | Flat key-value (all strings, no fields) | Error messages, UI strings, translations |
+
+### Storage Examples
+
+**Singleton** (`content/{domain}/{model}/{locale}.json`):
+```json
+{ "cta": "Get Started", "title": "Build faster" }
+```
+
+**Collection** (`content/{domain}/{model}/{locale}.json`):
+```json
+{
+  "a1b2c3d4e5f6": { "name": "Ahmet", "role": "CEO" },
+  "f6e5d4c3b2a1": { "name": "Jane", "role": "CTO" }
+}
+```
+
+**Document** (`content/{domain}/{model}/{slug}/{locale}.md`):
+```markdown
+---
+title: Getting Started
+slug: getting-started
+---
+# Getting Started with Contentrain
+```
+
+**Dictionary** (`content/{domain}/{model}/{locale}.json`):
+```json
+{ "auth.expired": "Session expired", "auth.failed": "Authentication failed" }
+```
+
+## Content Format Essentials
+
+- **Canonical serialization:** Keys sorted lexicographically, 2-space indent, UTF-8, trailing newline, omit nulls/defaults
+- **System fields** (auto-managed, never set manually): `id` (collection), `slug` (document), `createdAt`/`updatedAt` (Git-derived), `status`/`source`/`updated_by`/`approved_by` (metadata)
+- **IDs:** 12-char hex, auto-generated for collections
+- **Object-map rationale:** Sorted keys produce predictable diffs, minimize Git merge conflicts
+
+## MCP Tool Catalog
+
+| Tool | Purpose |
+|------|---------|
+| `contentrain_status` | Get full project state in one call |
+| `contentrain_describe` | Get schema + optional sample for one model |
+| `contentrain_describe_format` | Get storage and file-format contract |
+| `contentrain_init` | Initialize `.contentrain/` directory |
+| `contentrain_scaffold` | Generate models from built-in template |
+| `contentrain_model_save` | Create or update a model definition (upsert) |
+| `contentrain_model_delete` | Delete a model and its content |
+| `contentrain_content_save` | Create or update content entries (upsert) |
+| `contentrain_content_delete` | Delete a content entry |
+| `contentrain_content_list` | List content entries for a model |
+| `contentrain_scan` | Scan project for structure or content candidates |
+| `contentrain_apply` | Apply normalize operation (extract or reuse) |
+| `contentrain_validate` | Validate content against model schemas |
+| `contentrain_submit` | Push contentrain/* branches to remote |
+| `contentrain_bulk` | Run batch operations on existing content |
+
+## Calling Sequences
+
+### Generate (New Project)
+```
+status --> init --> scaffold? --> model_save --> content_save --> validate --> submit
+```
+
+### Existing Project
+```
+status --> describe --> content_save --> validate --> submit
+```
+
+### Normalize Phase 1 (Extraction)
+```
+status --> init? --> scan(graph) --> scan(candidates) --> [agent evaluates]
+  --> apply(extract, dry_run:true) --> [review] --> apply(extract, dry_run:false)
+  --> validate --> submit
+```
+
+### Normalize Phase 2 (Reuse)
+```
+apply(reuse, dry_run:true) --> [review] --> apply(reuse, dry_run:false)
+  --> validate --> submit --> [repeat per model]
+```
+
+## Key Guardrails
+
+1. **Always call `contentrain_status` first** when working with an existing project
+2. **Always call `contentrain_describe_format` before creating models or content** to understand storage formats
+3. **Always `dry_run: true` first** for any `contentrain_apply` operation, review, then `dry_run: false`
+4. **Always `contentrain_validate` before `contentrain_submit`** -- fix errors before submitting
+5. **Dictionary = flat key-value, all strings, no fields, no id/slug** -- keys are semantic addresses
+6. **Collection = object-map by entry ID, typed fields** -- IDs are auto-generated 12-char hex
+7. **Never write to `.contentrain/meta/`, `.contentrain/client/`, or `.contentrain/context.json`** directly
+8. **Normalize branches always use review workflow** -- never auto-merge
+9. **MCP is deterministic infra, agent is intelligence** -- MCP does NOT make content decisions
+10. **Batch related changes** before validate/submit -- do not submit after every save
+
+## References
+
+| Reference | Description |
+|-----------|-------------|
+| [Schema Types](references/schema-types.md) | Complete 27-type catalog with field properties |
+| [Model Kinds](references/model-kinds.md) | Detailed storage formats, relations, nesting rules |
+| [Content Formats](references/content-formats.md) | Directory structure, config.json, canonical serialization |
+| [MCP Tools](references/mcp-tools.md) | Complete tool parameters and usage details |
+| [MCP Pipelines](references/mcp-pipelines.md) | Calling sequences, error handling, Studio hints |
+| [Architecture](references/architecture.md) | Full Contentrain schema and type architecture |
+| [i18n](references/i18n.md) | Internationalization quality rules |
+| [Security](references/security.md) | XSS prevention, secret detection, URL validation |
+| [Workflow](references/workflow.md) | Git workflow, branch naming, conflict resolution |