Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions ai/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,13 @@

| Path | Audience | In npm package |
|---|---|---|
| [`skills/`](skills/) | Agents building an app with `native-dates` | Planned (pre-1.0) |
| [`skills/`](skills/) | Agents building an app with `native-dates` | Yes |
| [`contributing/`](contributing/README.md) | Contributors working on `native-dates` | No |
| `workspace/` | Local scratch files, ignored by git | No |

## Consumer Skills

Files in [skills](skills/) will be included in the npm package for coding agents reading from installed dependencies, served by the docs site at `/skills/<skill>.md`, and listed in `/llms.txt` once authored (`contributing/plan/roadmap.md`).
Files in [skills](skills/) ([`native-dates.md`](skills/native-dates.md) and [`native-dates-plugins.md`](skills/native-dates-plugins.md)) are included in the npm package for coding agents reading from installed dependencies, served by the docs site at `/skills/<skill>.md`, and listed in `/llms.txt` and `/llms-full.txt`.

Downstream agents receive a skill on its own without the rest of this repository. Read the [authoring standard](contributing/standards/ai-author-context.md) and the [skill workflow](contributing/workflows/author-user-skill.md) before writing or editing one.

Expand Down
1 change: 1 addition & 0 deletions ai/contributing/plan/landed.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ Completed roadmap items, newest first. When a planned feature in [`roadmap.md`](

| Date | Milestone | Summary | Brotli delta |
|---|---|---|---|
| 2026-11-20 | Consumer agent skills | Downstream usage skills in [`ai/skills/`](../../skills/native-dates.md) published with the npm package and served at `/skills/<name>.md`, `/llms.txt`, and `/llms-full.txt` | 0 B |
| 2026-11-20 | North star | Project goals and design principles in [`north-star.md`](../north-star.md) | 0 B |
| 2026-11-19 | Test suite | Unit and Chromium Playwright test suites across core, plugins, and polyfill | 0 B |
| 2026-11-18 | Type declarations | Hand-authored `.d.ts` declarations, JSDoc examples, and `@see` links to `nativedates.dev` | 0 B |
Expand Down
1 change: 0 additions & 1 deletion ai/contributing/plan/roadmap.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,6 @@ Larger features with open design details keep a spec in `scopes/<name>.md`.

| Feature | Status | Summary |
|---|---|---|
| Consumer agent skills | Ready to build | Publish downstream usage skills in `ai/skills/` with the npm package and serve them at `/skills/<name>.md` and `/llms.txt` on the docs site |
| Benchmark suite | Needs design | Automated browser benchmark suite in `bench/` measuring parsing, arithmetic, formatting, and range iteration across changes |
| Documentation translations | Ready to build | Translated and reviewed guides, API references, and examples across the 8 supported locales |

Expand Down
Empty file removed ai/skills/.gitkeep
Empty file.
198 changes: 198 additions & 0 deletions ai/skills/native-dates-plugins.md

Large diffs are not rendered by default.

340 changes: 340 additions & 0 deletions ai/skills/native-dates.md

Large diffs are not rendered by default.

46 changes: 46 additions & 0 deletions docs/src/lib/skills.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
// reads downstream user skills from ai/skills/**/*.md for /skills/<skill>.md and /llms*.txt
import { existsSync, readdirSync, readFileSync } from 'node:fs';
import { basename, resolve } from 'node:path';
import { parse } from 'yaml';

import { PACKAGE_DIR } from './sizes.js';

const AUDIENCE_ORDER = ['essentials', 'usage', 'authoring'];

function walkMarkdown(dir) {
if (!existsSync(dir)) { return []; }
return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
const full = resolve(dir, entry.name);
if (entry.isDirectory()) { return walkMarkdown(full); }
return entry.isFile() && entry.name.endsWith('.md') && entry.name !== 'README.md' ? [full] : [];
});
}

export function shippedSkills() {
const skillsRoot = resolve(PACKAGE_DIR, 'ai/skills');
return walkMarkdown(skillsRoot)
.map((file) => {
const raw = readFileSync(file, 'utf8');
const [, front = '', body = raw] = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/) ?? [];
const data = front ? parse(front) : {};
const stem = basename(file, '.md');
const skill = data.skill ?? stem;
return {
skill,
title: data.title ?? skill,
description: data.description ?? '',
audience: data.audience ?? 'usage',
keywords: data.keywords ?? [],
type: data.type ?? 'skill',
raw,
body: `${body.replace(/^\s*<!--[\s\S]*?-->\s*/, '').trim()}\n`,
};
})
.sort((a, b) => {
const rank = (audience) => {
const index = AUDIENCE_ORDER.indexOf(audience);
return index === -1 ? AUDIENCE_ORDER.length : index;
};
return rank(a.audience) - rank(b.audience) || a.skill.localeCompare(b.skill);
});
}
18 changes: 14 additions & 4 deletions docs/src/pages/llms-full.txt.js
Original file line number Diff line number Diff line change
@@ -1,12 +1,22 @@
// /llms-full.txt: every docs page's markdown in one file, in the sidebar's order
// /llms-full.txt: downstream agent skills first, followed by every docs page in sidebar order
import { getCollection } from 'astro:content';

import { SECTIONS } from '../lib/nav.js';
import { markdownFor } from '../lib/page-markdown.js';
import { shippedSkills } from '../lib/skills.js';

export async function GET({ site }) {
const skills = shippedSkills().map((entry) =>
`<!-- ${new URL(`/skills/${entry.skill}.md`, site).href} -->\n\n${entry.body}`
);
const docs = new Map((await getCollection('docs')).map((e) => [e.id, e]));
const order = [...new Set(SECTIONS.flatMap((s) => s.groups.flatMap((g) => g.items.map((it) => it.slug.split('#')[0]))))];
const pages = order.filter((id) => docs.has(id)).map((id) => `<!-- ${new URL(`/${id}/`, site).href} -->\n\n${markdownFor(docs.get(id))}`);
return new Response(pages.join('\n---\n\n'), { headers: { 'content-type': 'text/plain; charset=utf-8' } });
const order = [
...new Set(SECTIONS.flatMap((s) => s.groups.flatMap((g) => g.items.map((it) => it.slug.split('#')[0])))),
];
const pages = order.filter((id) => docs.has(id)).map((id) =>
`<!-- ${new URL(`/${id}/`, site).href} -->\n\n${markdownFor(docs.get(id))}`
);
return new Response([...skills, ...pages].join('\n---\n\n'), {
headers: { 'content-type': 'text/plain; charset=utf-8' },
});
}
16 changes: 12 additions & 4 deletions docs/src/pages/llms.txt.js
Original file line number Diff line number Diff line change
@@ -1,14 +1,20 @@
import { getCollection } from 'astro:content';

import { SECTIONS } from '../lib/nav.js';
import { shippedSkills } from '../lib/skills.js';

// links docs pages to /<slug>.md and examples to /<slug>/ because examples have no raw markdown route
// links agent skills first, then docs pages to /<slug>.md and examples to /<slug>/
export async function GET({ site }) {
const docs = new Map((await getCollection('docs')).map((e) => [e.id, e]));
const examples = new Map((await getCollection('examples')).map((e) => [`examples/${e.id}`, e]));
const url = (path) => new URL(path, site).href;

const sections = SECTIONS.map((section) => {
const skillLines = shippedSkills().map((entry) =>
`- [${entry.title}](${url(`/skills/${entry.skill}.md`)}): ${entry.description}`
);
const skillSection = skillLines.length ? [`## Agent Skills\n\n${skillLines.join('\n')}`] : [];

const docSections = SECTIONS.map((section) => {
const seen = new Set();
const lines = section.groups.flatMap((g) => g.items).flatMap(({ slug }) => {
if (slug.includes('#') || seen.has(slug)) { return []; }
Expand All @@ -26,9 +32,11 @@ export async function GET({ site }) {

> A readable, immutable date and time library built on the browser's Temporal and Intl APIs with zero dependencies. Core includes zoned datetimes, calendar dates, times, durations, year-months, month-days, ranges, formatting, and relative time. Opt-in subpath plugins add city and abbreviation zones, loose parsing, and legacy Date methods.

Every page below is also served as markdown at its path plus \`.md\`. The full docs in one file: ${url('/llms-full.txt')}
Every page below is also served as markdown at its path plus \`.md\`. The full docs in one file: ${
url('/llms-full.txt')
}

${sections.join('\n\n')}
${[...skillSection, ...docSections].join('\n\n')}
`;
return new Response(body, { headers: { 'content-type': 'text/plain; charset=utf-8' } });
}
14 changes: 14 additions & 0 deletions docs/src/pages/skills/[name].md.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
import { shippedSkills } from '../../lib/skills.js';

export function getStaticPaths() {
return shippedSkills().map((entry) => ({
params: { name: entry.skill },
props: { skill: entry },
}));
}

export function GET({ props }) {
return new Response(props.skill.raw, {
headers: { 'content-type': 'text/markdown; charset=utf-8' },
});
}
2 changes: 2 additions & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@
"files": [
"src",
"types",
"ai/skills",
"!ai/README.md",
"README.md",
"LICENSE"
],
Expand Down
15 changes: 14 additions & 1 deletion tools/gates/ai.js
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
// validates markdown links, #anchors, GFM tables, unclosed fences, ai/ paths, and AGENTS.md symlinks
// validates YAML frontmatter, markdown links, #anchors, GFM tables, unclosed fences, ai/ paths, and AGENTS.md symlinks

import { existsSync, lstatSync, readdirSync, readFileSync, readlinkSync, statSync } from 'node:fs';
import { dirname, relative, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { parse as parseYaml } from 'yaml';

import { checkDecisions } from './decisions-index.js';

Expand Down Expand Up @@ -99,12 +100,24 @@ function countCells(line) {
export function checkMarkdownStructure(source) {
const lines = source.split('\n');
const findings = [];
let startIndex = 0;
const frontMatch = /^---\n([\s\S]*?)\n---(?:\n|$)/.exec(source);
if (frontMatch) {
startIndex = frontMatch[0].split('\n').length - (frontMatch[0].endsWith('\n') ? 1 : 0);
try {
parseYaml(frontMatch[1]);
}
catch (err) {
findings.push(`L1: invalid YAML frontmatter (${err.message.split('\n')[0]})`);
}
}
let fence = null;
let fenceLine = 0;
let table = null;
let previous = '';

lines.forEach((line, index) => {
if (index < startIndex) { return; }
const lineNumber = index + 1;
const fenceMatch = /^\s*(`{3,}|~{3,})/.exec(line);
if (fenceMatch) {
Expand Down
42 changes: 42 additions & 0 deletions tools/gates/ai.test.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
import { describe, expect, it } from 'vitest';

import { checkMarkdownStructure } from './ai.js';

describe('ai gate markdown structure', () => {
it('accepts quoted YAML frontmatter scalars containing colons and braces', () => {
const doc = [
'---',
'title: Plugins Guide',
'description: "Use { loose: true } and configure({ dayFirst: true }) safely."',
'keywords: ["@native-dates/plugins", loose]',
'audience: usage',
'skill: native-dates-plugins',
'type: skill',
'---',
'',
'# Plugins Guide',
'',
'| Col A | Col B |',
'|---|---|',
'| 1 | 2 |',
'',
].join('\n');

expect(checkMarkdownStructure(doc)).toEqual([]);
});

it('flags invalid unquoted YAML mappings in frontmatter', () => {
const broken = [
'---',
'title: Plugins Guide',
'description: Use { loose: true } without quotes',
'---',
'',
'# Plugins Guide',
].join('\n');

const findings = checkMarkdownStructure(broken);
expect(findings).toHaveLength(1);
expect(findings[0]).toMatch(/^L1: invalid YAML frontmatter/);
});
});