@contentrain/skills 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Contentrain
+
+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

@@ -0,0 +1,102 @@
+# `@contentrain/skills`
+
+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:
+
+- 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
+
+```bash
+pnpm add @contentrain/skills
+```
+
+## 📦 What It Contains
+
+### Workflow skills
+
+Published under `workflows/*`:
+
+- `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`
+
+### 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:
+
+- `WORKFLOW_SKILLS`
+- `FRAMEWORK_GUIDES`
+
+## 🧪 Example
+
+```ts
+import { WORKFLOW_SKILLS, FRAMEWORK_GUIDES } from '@contentrain/skills'
+
+console.log(WORKFLOW_SKILLS)
+console.log(FRAMEWORK_GUIDES.includes('next'))
+```
+
+## 🧠 Design Role
+
+`@contentrain/skills` is for step-by-step execution guidance:
+
+- `skills` = procedures and operational playbooks
+- `rules` = policy and non-negotiable constraints
+
+In practice:
+
+- use `@contentrain/rules` to understand what is allowed
+- use `@contentrain/skills` to decide which workflow to run next
+
+## 🔗 Relationship To Other Packages
+
+- `@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
+
+## 🛠 Build
+
+From the monorepo root:
+
+```bash
+pnpm --filter @contentrain/skills build
+pnpm --filter @contentrain/skills test
+pnpm --filter @contentrain/skills typecheck
+```
+
+## 📄 License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,35 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/index.ts
+/**
+* @contentrain/skills — AI agent skills for Contentrain
+*
+* Step-by-step workflow procedures and framework integration guides.
+*/
+const WORKFLOW_SKILLS = [
+	"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"
+];
+const FRAMEWORK_GUIDES = [
+	"nuxt",
+	"next",
+	"astro",
+	"sveltekit",
+	"vue",
+	"react",
+	"expo",
+	"react-native",
+	"node"
+];
+//#endregion
+exports.FRAMEWORK_GUIDES = FRAMEWORK_GUIDES;
+exports.WORKFLOW_SKILLS = WORKFLOW_SKILLS;

package/dist/index.d.cts

@@ -0,0 +1,13 @@
+//#region src/index.d.ts
+/**
+ * @contentrain/skills — AI agent skills for Contentrain
+ *
+ * Step-by-step workflow procedures and framework integration guides.
+ */
+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 };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +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"}

package/dist/index.d.mts

@@ -0,0 +1,13 @@
+//#region src/index.d.ts
+/**
+ * @contentrain/skills — AI agent skills for Contentrain
+ *
+ * Step-by-step workflow procedures and framework integration guides.
+ */
+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 };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +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"}

package/dist/index.mjs

@@ -0,0 +1,35 @@
+//#region src/index.ts
+/**
+* @contentrain/skills — AI agent skills for Contentrain
+*
+* Step-by-step workflow procedures and framework integration guides.
+*/
+const WORKFLOW_SKILLS = [
+	"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"
+];
+const FRAMEWORK_GUIDES = [
+	"nuxt",
+	"next",
+	"astro",
+	"sveltekit",
+	"vue",
+	"react",
+	"expo",
+	"react-native",
+	"node"
+];
+//#endregion
+export { FRAMEWORK_GUIDES, WORKFLOW_SKILLS };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +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"}

package/frameworks/astro.md

@@ -0,0 +1,334 @@
+# Contentrain + Astro
+
+> Framework guide for consuming Contentrain-managed content in Astro projects.
+
+---
+
+## 1. Setup
+
+### 1.1 SDK Installation
+
+```bash
+pnpm add @contentrain/query   # or npm/yarn
+npx contentrain generate
+```
+
+The generator reads `.contentrain/models/` and produces a typed client in `.contentrain/client/`. Your `package.json` must include the subpath import:
+
+```json
+{
+  "imports": {
+    "#contentrain": {
+      "types": "./.contentrain/client/index.d.ts",
+      "import": "./.contentrain/client/index.mjs",
+      "require": "./.contentrain/client/index.cjs",
+      "default": "./.contentrain/client/index.mjs"
+    }
+  }
+}
+```
+
+The generator adds this automatically. Restart the Astro dev server after initial generation.
+
+### 1.2 Watch Mode
+
+Run the generator alongside Astro dev:
+
+```bash
+npx contentrain generate --watch &
+npx astro dev
+```
+
+---
+
+## 2. Imports
+
+All SDK functions are imported from the `#contentrain` subpath:
+
+```ts
+import { query, singleton, dictionary, document } from '#contentrain'
+```
+
+This import works in `.astro` component frontmatter, API routes, and any server-side script. The SDK reads JSON files from the file system — no runtime API calls.
+
+---
+
+## 3. Querying Content
+
+### 3.1 Collections
+
+```ts
+const posts = query('blog-post').locale('en').all()
+const featured = query('blog-post').locale('en').where('featured', true).all()
+const sorted = query('blog-post').locale('en').sort('publishedAt', 'desc').all()
+const post = query('blog-post').locale('en').where('id', 'abc-123').first()
+```
+
+### 3.2 Singletons
+
+```ts
+const hero = singleton('hero').locale('en').get()
+```
+
+### 3.3 Dictionaries
+
+```ts
+const label = dictionary('ui-labels').locale('en').get('submit_button')
+const allLabels = dictionary('ui-labels').locale('en').get()
+```
+
+### 3.4 Documents
+
+```ts
+const article = document('blog-article').locale('en').bySlug('getting-started')
+```
+
+### 3.5 Relations
+
+```ts
+const posts = query('blog-post').locale('en').include('author', 'tags').all()
+// post.author → full author object
+// post.tags → array of full tag objects
+```
+
+---
+
+## 4. Astro Integration Patterns
+
+### 4.1 Page Components
+
+SDK calls go in the frontmatter (the `---` fenced section):
+
+```astro
+---
+import { query } from '#contentrain'
+
+const posts = query('blog-post').locale('en').sort('publishedAt', 'desc').all()
+---
+
+<ul>
+  {posts.map(post => (
+    <li><a href={`/blog/${post.slug}`}>{post.title}</a></li>
+  ))}
+</ul>
+```
+
+### 4.2 Dynamic Routes
+
+For `src/pages/blog/[slug].astro`:
+
+```astro
+---
+import { query, document } from '#contentrain'
+
+export function getStaticPaths() {
+  const posts = query('blog-post').locale('en').all()
+  return posts.map(post => ({
+    params: { slug: post.slug },
+    props: { post }
+  }))
+}
+
+const { post } = Astro.props
+---
+
+<article>
+  <h1>{post.title}</h1>
+</article>
+```
+
+### 4.3 Layout Data
+
+Provide global content (navigation, footer) from layouts:
+
+```astro
+---
+import { singleton, dictionary } from '#contentrain'
+
+const nav = singleton('navigation').locale('en').get()
+const footerLabels = dictionary('footer-labels').locale('en').get()
+---
+
+<nav>
+  {nav.items.map(item => <a href={item.url}>{item.label}</a>)}
+</nav>
+<slot />
+<footer>
+  <!-- footer content -->
+</footer>
+```
+
+---
+
+## 5. i18n Integration
+
+### 5.1 Astro Built-in i18n
+
+Astro provides built-in i18n routing. Combine it with Contentrain locale support:
+
+```astro
+---
+// src/pages/[locale]/blog/[slug].astro
+import { document } from '#contentrain'
+
+export function getStaticPaths() {
+  const locales = ['en', 'tr', 'de']
+  const paths = []
+  for (const locale of locales) {
+    const posts = document('blog-article').locale(locale).all()
+    for (const post of posts) {
+      paths.push({
+        params: { locale, slug: post.slug },
+        props: { post, locale }
+      })
+    }
+  }
+  return paths
+}
+
+const { post } = Astro.props
+---
+
+<article>
+  <h1>{post.title}</h1>
+</article>
+```
+
+### 5.2 Current Locale Access
+
+Use `Astro.currentLocale` (available when i18n is configured in `astro.config.mjs`) to pass the locale to SDK calls:
+
+```astro
+---
+import { query } from '#contentrain'
+
+const locale = Astro.currentLocale ?? 'en'
+const posts = query('blog-post').locale(locale).all()
+---
+```
+
+### 5.3 Dictionary Strings
+
+Contentrain dictionaries can serve as the translation source for UI strings:
+
+```astro
+---
+import { dictionary } from '#contentrain'
+
+const locale = Astro.currentLocale ?? 'en'
+const t = dictionary('ui-labels').locale(locale).get()
+---
+
+<button>{t.submit_button}</button>
+<p>{t.welcome_message}</p>
+```
+
+---
+
+## 6. Content Collections Integration
+
+### 6.1 Astro Content Collections
+
+Astro's content collections can coexist with Contentrain. Define a collection that points to `.contentrain/content/`:
+
+```ts
+// src/content/config.ts
+import { defineCollection, z } from 'astro:content'
+
+const blog = defineCollection({
+  type: 'content',
+  schema: z.object({
+    title: z.string(),
+    description: z.string(),
+    publishedAt: z.string()
+  })
+})
+
+export const collections = { blog }
+```
+
+Symlink or copy `.contentrain/content/blog/` to `src/content/blog/` if using Astro's content layer, or use the SDK directly for simpler setups.
+
+### 6.2 Markdown Rendering
+
+For document-kind entries with markdown bodies, render them using Astro's built-in markdown support or a markdown component:
+
+```astro
+---
+import { document } from '#contentrain'
+
+const article = document('blog-article').locale('en').bySlug('getting-started')
+---
+
+<article>
+  <h1>{article.title}</h1>
+  <Fragment set:html={article.bodyHtml} />
+</article>
+```
+
+---
+
+## 7. Islands Architecture
+
+### 7.1 Static Parent, Dynamic Child
+
+Content data is fetched in the static Astro component and passed to interactive island components as props:
+
+```astro
+---
+import { query } from '#contentrain'
+import SearchWidget from '../components/SearchWidget.tsx'
+
+const posts = query('blog-post').locale('en').all()
+---
+
+<!-- Static content -->
+<h1>Blog</h1>
+
+<!-- Interactive island with content data -->
+<SearchWidget client:load posts={posts} />
+```
+
+The content is embedded in the static HTML. The island component receives it as serialized props — no client-side data fetching required.
+
+---
+
+## 8. Build and Deployment
+
+### 8.1 Static Output (Default)
+
+Astro builds static HTML by default. All SDK calls resolve at build time:
+
+```bash
+npx astro build
+```
+
+Output goes to `dist/`. Content is baked into the HTML — zero runtime dependencies.
+
+### 8.2 SSR Mode
+
+With SSR enabled (`output: 'server'` or `output: 'hybrid'` in `astro.config.mjs`), SDK calls execute on the server at request time. Content is still file-based.
+
+### 8.3 Deployment Flow
+
+1. Content changes are committed to Git via MCP tools.
+2. Push triggers platform rebuild (Vercel, Netlify, Cloudflare Pages).
+3. `astro build` runs, SDK reads `.contentrain/` content.
+4. Static pages are generated with embedded content.
+
+---
+
+## 9. Type Safety
+
+The generated client provides full TypeScript types:
+
+```ts
+import { query } from '#contentrain'
+
+// Fully typed — autocomplete for all fields
+const posts = query('blog-post').locale('en').all()
+posts[0].title    // string
+posts[0].author   // Author type when using .include('author')
+```
+
+Keep the generator running in watch mode during development to stay in sync with model changes.

package/frameworks/expo.md

@@ -0,0 +1,66 @@
+# Contentrain + Expo / React Native
+
+> Framework guide for Metro-style consumers of the generated Contentrain client.
+
+---
+
+## 1. Setup
+
+```bash
+pnpm add @contentrain/query
+npx contentrain generate
+```
+
+The generated client exposes a CommonJS bootstrap path for Metro-like consumers.
+
+---
+
+## 2. Bootstrap Pattern
+
+Use the CJS wrapper and initialize it once:
+
+```ts
+// app/content.ts
+let clientPromise: Promise<any> | null = null
+
+export function getContentrainClient() {
+  if (!clientPromise) {
+    clientPromise = require('#contentrain').init()
+  }
+  return clientPromise
+}
+```
+
+Then use it from app code:
+
+```tsx
+import { useEffect, useState } from 'react'
+import { Text, View } from 'react-native'
+import { getContentrainClient } from './content'
+
+export function HomeScreen() {
+  const [title, setTitle] = useState('')
+
+  useEffect(() => {
+    getContentrainClient().then((client) => {
+      setTitle(client.singleton('hero').locale('en').get().title)
+    })
+  }, [])
+
+  return (
+    <View>
+      <Text>{title}</Text>
+    </View>
+  )
+}
+```
+
+---
+
+## 3. Rules
+
+- use `require('#contentrain').init()` for the bootstrap
+- cache the promise; do not initialize on every render
+- treat the client as read-only generated data
+- re-run `contentrain generate` after content/model changes
+