Add OpenSkill descriptions for human capabilities and OpenProfile discovery

apps/logicsrc-web/contract/openskill.contract.test.ts

@@ -0,0 +1,56 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import { readSkill, SKILL_SLUGS, listSkills, summarizeSkill } from "../src/lib/skills";
+import { GET } from "../src/app/openskill/[slug]/openskill.md/route";
+import { GET as catalogMarkdown } from "../src/app/openskill/catalog.md/route";
+import { buildRedirects } from "../next.config";
+
+describe("OpenSkill capability records", () => {
+  it("provides a portable index whose links resolve to the published record sources", async () => {
+    const response = catalogMarkdown();
+    expect(response.headers.get("content-type")).toBe("text/markdown; charset=utf-8");
+    const body = await response.text();
+    const paths = [...body.matchAll(/\]\((https?:\/\/[^)]+\/openskill\/([^/]+)\/openskill\.md)\)/g)];
+    expect(paths).toHaveLength(SKILL_SLUGS.length);
+    for (const [, , slug] of paths) expect(readSkill(slug)).not.toBeNull();
+  });
+
+  it("serves every published record losslessly as cross-origin Markdown", async () => {
+    for (const slug of SKILL_SLUGS) {
+      const source = readFileSync(resolve(process.cwd(), `../../docs/openskill/${slug}.md`), "utf8");
+      const response = await GET(new Request(`https://example.com/openskill/${slug}/openskill.md`), { params: Promise.resolve({ slug }) });
+      expect(response.status).toBe(200);
+      expect(response.headers.get("content-type")).toBe("text/markdown; charset=utf-8");
+      expect(response.headers.get("access-control-allow-origin")).toBe("*");
+      expect(response.headers.get("content-disposition")).toBeNull();
+      expect(await response.text()).toBe(source);
+    }
+  });
+
+  it("does not expose unlisted files or resolve request paths as filesystem paths", async () => {
+    for (const slug of ["unknown", "../openprofile", "../../package.json", "__proto__"]) {
+      expect(readSkill(slug)).toBeNull();
+      const response = await GET(new Request("https://example.com"), { params: Promise.resolve({ slug }) });
+      expect(response.status).toBe(404);
+    }
+  });
+
+  it("keeps knowledge, capabilities and occupations distinct in the catalog", () => {
+    const catalog = listSkills();
+    expect(catalog.find((c) => c.slug === "logo-design")?.kind).toBe("skill");
+    expect(catalog.find((c) => c.slug === "accounting")?.kind).toBe("knowledge");
+    expect(catalog.find((c) => c.slug === "accountant")?.kind).toBe("occupation");
+    expect(catalog.every((c) => c.name && c.description)).toBe(true);
+  });
+
+  it("does not infer a kind or consume metadata from examples or later sections", () => {
+    const source = "# Weaving\n\nMake interlaced textiles.\n\n```markdown\n- **Kind**: occupation\n```\n\n## Notes\n\n- **Kind**: knowledge\n";
+    expect(summarizeSkill(source, "weaving")).toEqual({ slug: "weaving", name: "Weaving", description: "Make interlaced textiles." });
+    expect(summarizeSkill("# Unusual craft\n\n- **Kind**: local-category\n\nA local practice.", "craft").kind).toBe("local-category");
+  });
+
+  it("lets the OpenProfile skills path discover the same concept catalog", () => {
+    expect(buildRedirects()).toContainEqual({ source: "/openprofile/skills", destination: "/openskill", permanent: true });
+  });
+});

apps/logicsrc-web/contract/spec-discovery.contract.test.ts

@@ -10,6 +10,7 @@ vi.mock("../src/lib/supabase", () => ({ publicClient: () => { throw new Error("o
 
 describe.each([
   { slug: "openagent", name: "OpenAgent", family: "people" },
+  { slug: "openskill", name: "OpenSkill", family: "people" },
   { slug: "openabtest", name: "OpenABTest", family: "process" },
   { slug: "openfleet", name: "OpenFleet", family: "process" },
   { slug: "openrental", name: "OpenRental", family: "catalogs" },

apps/logicsrc-web/e2e/openskill.spec.ts

@@ -0,0 +1,22 @@
+import { expect, test } from "@playwright/test";
+
+test("human capabilities are discoverable and their Markdown can travel independently", async ({ page, request }) => {
+  await page.goto("/openprofile/skills");
+  await expect(page).toHaveURL(/\/openskill$/);
+  await expect(page.getByRole("heading", { name: "OpenSkill", exact: true })).toBeVisible();
+  expect(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth)).toBe(true);
+
+  await page.getByRole("link", { name: "Logo design", exact: true }).click();
+  await expect(page.getByRole("heading", { name: "Logo design", exact: true })).toBeVisible();
+  const sourceLink = page.getByRole("link", { name: "Markdown source", exact: true });
+  const source = await request.get((await sourceLink.getAttribute("href"))!);
+  expect(source.status()).toBe(200);
+  expect(source.headers()["content-type"]).toBe("text/markdown; charset=utf-8");
+  expect(await source.text()).toContain("# Logo design");
+  expect(await source.text()).toContain("**Kind**: skill");
+
+  const index = await request.get("/openskill/catalog.md");
+  expect(index.status()).toBe(200);
+  expect(index.headers()["content-type"]).toBe("text/markdown; charset=utf-8");
+  expect(await index.text()).toContain("/openskill/accountant/openskill.md");
+});

apps/logicsrc-web/next.config.ts

@@ -79,7 +79,10 @@ export function buildRewrites(
  * page. Permanent, so the old URL in the sitemap and in links keeps working.
  */
 export function buildRedirects() {
-  return [{ source: "/agent-swarm", destination: "/openfleet", permanent: true }];
+  return [
+    { source: "/agent-swarm", destination: "/openfleet", permanent: true },
+    { source: "/openprofile/skills", destination: "/openskill", permanent: true }
+  ];
 }
 
 const nextConfig: NextConfig = {

apps/logicsrc-web/src/app/.well-known/openprofile.md/route.ts

@@ -31,6 +31,7 @@ Open coordination standards for humans, AI agents, plugins, payment systems and
 
 - [OpenMCP](${SITE_URL}/openmcp): an open catalog of MCP relays, live at https://openmcp.logicsrc.com
 - [OpenProfile.md](${SITE_URL}/openprofile): one Markdown file for who and where, people and agents alike
+- [OpenSkill](${SITE_URL}/openskill): portable descriptions of human skills, knowledge and occupations
 - [ASDLC](${SITE_URL}/asdlc): the agentic software development lifecycle
 - [OpenCreds](${SITE_URL}/opencreds): end-to-end encrypted credential sharing
 - [Docs](${SITE_URL}/docs): every specification LogicSRC publishes

apps/logicsrc-web/src/app/llms.txt/route.ts

@@ -33,6 +33,8 @@ export function GET(): Response {
 - [Blog](${SITE_URL}/blog): Project notes and release announcements.
 - [Blog RSS](${SITE_URL}/blog/rss.xml): Machine-readable feed of posts.
 - [This site's OpenProfile.md](${SITE_URL}/.well-known/openprofile.md)
+- [OpenSkill concept catalog](${SITE_URL}/openskill): Human skills, knowledge and occupations. Each concept page links its portable openskill.md source; these are capability descriptions, not executable agent instructions.
+- [OpenSkill Markdown index](${SITE_URL}/openskill/catalog.md): Names, kinds, descriptions and direct links to every published concept record.
 
 ${families.join("\n\n")}
 

apps/logicsrc-web/src/app/openprofile/page.tsx

@@ -259,6 +259,10 @@ export default function OpenProfilePage(): ReactNode {
           <h2>Where everything lives</h2>
         </div>
         <ul style={{ color: "#41505d", lineHeight: 1.9, paddingLeft: "1.1rem" }}>
+          <li>
+            <Link href="/openprofile/skills">Skills and knowledge</Link>: portable human capabilities,
+            occupations and taxonomy links through OpenSkill
+          </li>
           <li>
             <Link href="/docs/openprofile">Specification</Link>, with the eight rules, discovery,
             verification and the version history

apps/logicsrc-web/src/app/openskill/[slug]/openskill.md/route.ts

@@ -0,0 +1,21 @@
+import { readSkill, SKILL_SLUGS } from "@/lib/skills";
+
+export const dynamic = "force-static";
+export const dynamicParams = false;
+export function generateStaticParams() {
+  return SKILL_SLUGS.map((slug) => ({ slug }));
+}
+
+export async function GET(_request: Request, { params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const source = readSkill(slug);
+  if (source === null) return new Response("Not found", { status: 404 });
+  return new Response(source, {
+    headers: {
+      "content-type": "text/markdown; charset=utf-8",
+      "access-control-allow-origin": "*",
+      "cache-control": "public, max-age=3600",
+      "x-content-type-options": "nosniff"
+    }
+  });
+}

apps/logicsrc-web/src/app/openskill/[slug]/page.tsx

@@ -0,0 +1,38 @@
+import Link from "next/link";
+import { notFound } from "next/navigation";
+import type { Metadata } from "next";
+import { marked } from "marked";
+import { SiteShell } from "@/components/site-shell";
+import { sanitizeRenderedHtml } from "@/lib/html";
+import { readSkill, SKILL_SLUGS, summarizeSkill } from "@/lib/skills";
+
+export const dynamicParams = false;
+export function generateStaticParams() {
+  return SKILL_SLUGS.map((slug) => ({ slug }));
+}
+
+export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }): Promise<Metadata> {
+  const { slug } = await params;
+  const source = readSkill(slug);
+  if (!source) return { title: "Not found · OpenSkill" };
+  const concept = summarizeSkill(source, slug);
+  return {
+    title: `${concept.name} · OpenSkill · LogicSRC`,
+    description: concept.description,
+    alternates: { canonical: `/openskill/${slug}`, types: { "text/markdown": `/openskill/${slug}/openskill.md` } }
+  };
+}
+
+export default async function SkillPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const source = readSkill(slug);
+  if (!source) notFound();
+  const concept = summarizeSkill(source, slug);
+  const html = sanitizeRenderedHtml(await marked.parse(source));
+  return <SiteShell crumbTitle={concept.name}>
+    <article className="band" style={{ maxWidth: "48rem" }}>
+      <p><Link href="/openskill">← All concepts</Link>{" · "}<a href={`/openskill/${slug}/openskill.md`}>Markdown source</a></p>
+      <div className="blog-content" style={{ lineHeight: 1.7 }} dangerouslySetInnerHTML={{ __html: html }} />
+    </article>
+  </SiteShell>;
+}

apps/logicsrc-web/src/app/openskill/catalog.md/route.ts

@@ -0,0 +1,23 @@
+import { listSkills } from "@/lib/skills";
+
+export const dynamic = "force-static";
+const SITE_URL = (process.env.PUBLIC_URL ?? "https://logicsrc.com").replace(/\/$/, "");
+
+export function GET() {
+  const records = listSkills().map((concept) =>
+    `- [${concept.name}](${SITE_URL}/openskill/${concept.slug}/openskill.md) — ${concept.kind ?? "kind unstated"}: ${concept.description}`
+  );
+  return new Response([
+    "# OpenSkill catalog", "",
+    "Portable descriptions of human skills, knowledge and occupations. These are concept definitions; personal claims and evidence belong in OpenProfile.", "",
+    `Specification: ${SITE_URL}/docs/openskill`, "",
+    ...records, ""
+  ].join("\n"), {
+    headers: {
+      "content-type": "text/markdown; charset=utf-8",
+      "access-control-allow-origin": "*",
+      "cache-control": "public, max-age=3600",
+      "x-content-type-options": "nosniff"
+    }
+  });
+}

apps/logicsrc-web/src/app/openskill/page.tsx

@@ -0,0 +1,52 @@
+import Link from "next/link";
+import type { Metadata } from "next";
+import { SiteShell } from "@/components/site-shell";
+import { listSkills } from "@/lib/skills";
+import { pre, table, td, th } from "../openontology/ui";
+
+export const metadata: Metadata = {
+  title: "OpenSkill · Human skills and knowledge · LogicSRC",
+  description: "Portable descriptions of human skills, knowledge and occupations, linked to ESCO and O*NET and carried in OpenProfile.",
+  alternates: { canonical: "/openskill" }
+};
+
+export default function OpenSkillPage() {
+  const concepts = listSkills();
+  return (
+    <SiteShell active="OpenSkill">
+      <section className="band">
+        <div className="section-head">
+          <p className="eyebrow">People and agents · Draft 0.1</p>
+          <h1>OpenSkill</h1>
+          <p>What you know. What you can do.</p>
+        </div>
+        <p>Branding, accounting, software engineering, hardware architecture. Describe a human capability in a small Markdown file, connect it to an established taxonomy, and carry it between profiles, portfolios and job boards.</p>
+        <p><Link className="button-primary" href="/docs/openskill">Read the specification</Link>{" · "}<Link href="/openprofile">Use it in OpenProfile</Link>{" · "}<a href="/openskill/catalog.md">Markdown catalog</a></p>
+      </section>
+      <section className="band">
+        <div className="section-head"><h2>A starting vocabulary</h2><p>Skills describe activity; knowledge describes a subject; occupations describe roles. Each entry has its own editable Markdown source.</p></div>
+        <div style={{ overflowX: "auto" }}>
+          <table style={table}>
+            <thead><tr><th style={th}>Concept</th><th style={th}>Kind</th><th style={th}>Description</th></tr></thead>
+            <tbody>{concepts.map((concept) => <tr key={concept.slug}>
+              <td style={td}><Link href={`/openskill/${concept.slug}`}>{concept.name}</Link></td>
+              <td style={td}>{concept.kind ?? "Unstated"}</td>
+              <td style={td}>{concept.description}</td>
+            </tr>)}</tbody>
+          </table>
+        </div>
+        <p>These initial examples cover design, finance and computing. The format accepts other domains and local concepts, including concepts with no taxonomy match.</p>
+      </section>
+      <section className="band">
+        <div className="section-head"><h2>Add it to your profile</h2><p>Plain words work. Links add a shared meaning.</p></div>
+        <pre style={pre}>{"## Skills\n\n- [Branding](https://logicsrc.com/openskill/branding)\n- [Logo design](https://logicsrc.com/openskill/logo-design)\n- Accounting\n- [Software engineer](https://logicsrc.com/openskill/software-engineer)"}</pre>
+        <p>A profile entry is a claim. Experience, self-assessment and evidence stay with the person making it. An occupation label does not establish a credential or a license.</p>
+      </section>
+      <section className="band">
+        <div className="section-head"><h2>Connected to existing knowledge</h2></div>
+        <p><a href="https://esco.ec.europa.eu/en/use-esco/use-esco-services-api/esco-web-service-api">ESCO</a> provides linked skills, knowledge and occupations. <a href="https://www.onetcenter.org/content.html">O*NET</a> describes occupations and their requirements. OpenSkill records explicit mappings, while keeping the description small enough to read and carry on its own.</p>
+        <p>These are descriptive capability records. Executable agent procedures retain their separate <code>SKILL.md</code> format. Reading a capability never installs a tool or grants it permission to act.</p>
+      </section>
+    </SiteShell>
+  );
+}

apps/logicsrc-web/src/app/sitemap.ts

@@ -2,6 +2,7 @@ import type { MetadataRoute } from "next";
 import { publicClient } from "@/lib/supabase";
 import { DOC_SLUGS } from "@/lib/docs";
 import { FAMILIES, allSpecs } from "@/lib/specs";
+import { SKILL_SLUGS } from "@/lib/skills";
 
 export const dynamic = "force-dynamic";
 
@@ -76,5 +77,8 @@ export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
     postEntries = [];
   }
 
-  return [...staticEntries, ...docEntries, ...postEntries];
+  const skills: MetadataRoute.Sitemap = SKILL_SLUGS.map((slug) => ({
+    url: `${base}/openskill/${slug}`, changeFrequency: "monthly", priority: 0.6
+  }));
+  return [...staticEntries, ...docEntries, ...skills, ...postEntries];
 }

apps/logicsrc-web/src/lib/skills.ts

@@ -0,0 +1,59 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { marked } from "marked";
+
+// Public concepts only. Read at build time; request paths never select files.
+export const SKILL_SLUGS = [
+  "branding", "logo-design", "graphic-design", "investing", "investor",
+  "financial-advisor", "accounting", "accountant", "software-development",
+  "developer", "software-engineer", "computer-science", "hardware-architectures",
+  "hardware-architect"
+] as const;
+
+const SKILLS_DIR = resolve(process.cwd(), "../../docs/openskill");
+
+export type SkillSummary = {
+  slug: string;
+  name: string;
+  description: string;
+  kind?: string;
+  domain?: string;
+  aliases?: string;
+};
+
+export function readSkill(slug: string): string | null {
+  if (!(SKILL_SLUGS as readonly string[]).includes(slug)) return null;
+  return readFileSync(resolve(SKILLS_DIR, `${slug}.md`), "utf8");
+}
+
+// A catalog view of the introduction, not a lossy replacement for the record.
+// Markdown tokenization keeps headings or bullets inside code fences inert.
+export function summarizeSkill(markdown: string, slug: string): SkillSummary {
+  const result: SkillSummary = { slug, name: slug, description: "" };
+  const tokens = marked.lexer(markdown);
+  const start = tokens.findIndex((token) => token.type === "heading" && token.depth === 1);
+  if (start < 0) return result;
+  const title = tokens[start];
+  if (title.type === "heading") result.name = title.text;
+  let identity = true;
+  for (const token of tokens.slice(start + 1)) {
+    if (token.type === "heading") break;
+    if (token.type === "space") continue;
+    if (token.type === "list" && identity) {
+      for (const item of token.items) {
+        const match = /^(?:\*\*)?(Kind|Domain|Aliases)(?:\*\*)?:\s*(.+)$/i.exec(item.text);
+        if (!match) continue;
+        const key = match[1].toLowerCase() as "kind" | "domain" | "aliases";
+        result[key] ??= match[2].trim();
+      }
+    } else {
+      identity = false;
+      if (token.type === "paragraph" && !result.description) result.description = token.text;
+    }
+  }
+  return result;
+}
+
+export function listSkills(): SkillSummary[] {
+  return SKILL_SLUGS.map((slug) => summarizeSkill(readSkill(slug)!, slug));
+}

apps/logicsrc-web/src/lib/specs.ts

@@ -51,6 +51,7 @@ export const FAMILIES: Family[] = [
       "One Markdown file for a person or an agent, served from their own domain and linked from every platform that has a page for them. The profile carries the identity, the accounts and the topics; the sections carry what a platform needs to match on, so a job board, a booking site or a dating app reads the file instead of asking forty questions again.",
     specs: [
       s("openprofile", "OpenProfile.md", "One Markdown file for who you are and where you are, people and agents alike", { status: "0.2" }),
+      s("openskill", "OpenSkill", "Portable descriptions of human skills, knowledge and occupations, linked from OpenProfile", { status: "draft" }),
       s("openagent", "OpenAgent", "A portable agent profile: identity, owner, skills and requested permissions", { status: "0.1" }),
       s("openwall", "OpenWall", "Consent-based broadcasts and direct messages across contact networks, with an AT Protocol mapping", { landing: undefined, status: "draft" }),
       s("openresume", "OpenResume.md", "What you have done, in the same spirit, linked from the profile", { landing: undefined }),

apps/logicsrc-web/src/styles.css

@@ -662,7 +662,7 @@ pre {
 
 @media (max-width: 720px) {
   .shell {
-    grid-template-columns: 1fr;
+    grid-template-columns: minmax(0, 1fr);
   }
 
   .rail {

docs/openprofile.md

@@ -160,6 +160,23 @@ Two rules a matching platform does not degrade on. **Born is the one key it must
 
 `## Photos` goes with it: one image URL per bullet, the first is the lead, and `Avatar` in the identity block stays the small square picture a directory shows next to the name.
 
+## Skills
+
+The optional `## Skills` section carries human capabilities, knowledge and occupations in plain language or as links to shared definitions. [OpenSkill](/docs/openskill) describes the portable concept records and their mappings to existing taxonomies such as ESCO and O*NET.
+
+```markdown
+## Skills
+
+- [Branding](https://logicsrc.com/openskill/branding)
+- [Logo design](https://logicsrc.com/openskill/logo-design)
+- Accounting
+- [Software engineer](https://logicsrc.com/openskill/software-engineer)
+```
+
+These are claims by the profile owner. Optional evidence, self-assessed level and last-used date can sit under a third-level heading for the skill, as described in OpenSkill. A concept definition does not establish a person's proficiency, employment or professional license. An occupation does not imply every associated skill. Unknown and unmapped labels remain valid, and readers retain this section even when they cannot interpret it. These capability descriptions do not install executable agent skills or authorize actions.
+
+[Browse the initial concepts](/openprofile/skills). This draft extension adds no required fields and does not change the existing discovery or verification rules.
+
 ## Discovery
 
 The file is served, not registered. There are three ways to find it, and a reader should try all three.
@@ -227,6 +244,7 @@ By hand, in any editor, in five minutes. Or:
 
 ## Related standards
 
+- [OpenSkill](/docs/openskill): human skills, knowledge and occupations linked from the optional Skills section.
 - [OpenResume.md](/docs/openresume): what you have done, in the same spirit. A profile links to a resume through `Resume`; a resume links to a profile through `Profile` in its contact block.
 - [OpenBroadcast](/docs/openbroadcast) and [OpenGuest](/docs/openguest): the `Broadcast` and `Guest` sections, for matching hosts with guests.
 - [OpenJob](/docs/openjob): what the work is.

docs/openskill.md

@@ -0,0 +1,146 @@
+# OpenSkill
+
+OpenSkill is a small, portable Markdown description of something a person can do, a subject they know, or an occupation they practise. Branding, logo design, investing, accounting, software engineering and hardware architecture can be named, described and linked from the same profile. People, organizations and agents can reference the same concepts.
+
+Status: **0.1 — draft**. This publication supplies a reference catalog and an optional OpenProfile section. It does not claim to catalog all human knowledge or to certify anyone's competence.
+
+Slug: `openskill`
+
+## The shape
+
+A name and a sentence are enough:
+
+```markdown
+# Logo design
+
+Create a recognizable visual mark that identifies a person, organization or product.
+```
+
+A publisher can add context without changing the format:
+
+```markdown
+# Logo design
+
+- **Id**: https://logicsrc.com/openskill/logo-design
+- **Kind**: skill
+- **Domain**: Design
+- **Language**: en
+- **Aliases**: logo creation, logo development
+
+Create a recognizable visual mark that identifies a person, organization or product.
+
+## Includes
+
+- Concept development, typography, geometry and optical balance.
+- Vector artwork, monochrome variants and small-size readability.
+
+## Related
+
+- [Branding](https://logicsrc.com/openskill/branding)
+
+## Taxonomy
+
+- **Broader match**: [ESCO: design graphics](http://data.europa.eu/esco/skill/f058bf62-70d1-4f5e-be2a-8b26fac24a96)
+```
+
+The concept describes the capability. A person's experience, proficiency and evidence belong in their profile. A brand's particular colors and logo files belong in its project brief.
+
+## Three kinds
+
+| Kind | What it describes | Examples |
+| --- | --- | --- |
+| `skill` | A capability expressed through activity | Branding, logo design, investing, software development |
+| `knowledge` | A subject someone understands | Accounting, computer science, hardware architectures |
+| `occupation` | A role that combines capabilities and knowledge | Investor, accountant, financial advisor, software engineer, hardware architect |
+
+Kind is optional; omission means unstated. Preserve unfamiliar kinds. A role does not establish every skill associated with it, and knowing a subject does not establish practical proficiency. The format can describe academic subjects, crafts, care work and other human capabilities beyond these initial examples.
+
+## Reading and writing
+
+The first top-level heading names the concept. The optional bullet list immediately below it carries `Key: value` pairs; bold keys are a display choice. The first prose paragraph before a second-level heading is the short description. Other prose and sections remain part of the document. Code fences are examples, not metadata.
+
+Common keys are `Id`, `Kind`, `Domain`, `Language` and `Aliases`. The Id is a stable absolute URI, independent of the displayed name or the location of a downloaded copy. If no Id exists, retain the source URL when there is one; a local unnamed identity stays local. Do not merge concepts solely because their names match. `Language` uses a BCP 47 tag; missing language stays unstated. Aliases are alternative labels for the same concept in the stated language, separated by commas. Domain is a browsing label, not a required taxonomy or a closed list.
+
+Useful sections include `Includes`, `Excludes`, `Broader`, `Related`, `Taxonomy` and `Examples`. Broader links name more general concepts; Related links connect associated concepts without declaring a hierarchy. A reader may follow more than one broader concept, and must bound traversal and handle cycles. Unknown keys, unknown sections and their original text are retained. Markdown remains the source; a search index or JSON view is derived from it.
+
+A translation keeps the concept Id when its meaning is unchanged and declares its own Language. A substantive scope change receives a new Id with a link to its predecessor. Do not silently turn a narrow skill into a broad occupation under an existing identifier.
+
+## Reuse existing taxonomies
+
+[ESCO](https://esco.ec.europa.eu/en/use-esco/use-esco-services-api/esco-web-service-api) supplies linked concepts for skills, knowledge and occupations. Its concept URIs identify the concepts across labels and languages. [O*NET](https://www.onetcenter.org/content.html) describes occupations together with knowledge, skills, abilities and work activities. These are useful foundations for work-related terms; neither is presented here as an exhaustive classification of all human knowledge. Other established subject vocabularies can be linked in the same way.
+
+OpenSkill provides a short description and explicit mappings. A reader can use the referenced taxonomy's classification when it needs more detail. A publisher does not need to download an entire taxonomy or obtain a central registration to describe a local concept.
+
+Under `## Taxonomy`, each bullet names its relationship and links to an actual concept:
+
+| Key | Meaning, from this concept to the linked concept |
+| --- | --- |
+| Exact match | Equivalent meaning and scope |
+| Close match | Substantial overlap with a meaningful difference |
+| Broader match | The linked concept is more general |
+| Narrower match | The linked concept is more specific |
+| Related match | Associated, with no equivalence or hierarchy claim |
+
+These correspond to [SKOS mapping properties](https://www.w3.org/TR/skos-reference/#mapping). They are statements by the document's publisher, not endorsements by the taxonomy owner. Inspect the referenced definition before selecting a relationship. A matching label, a search result or a model's guess is insufficient for an Exact match. Unmapped concepts are valid. Preserve the original URI, including an ESCO `http://data.europa.eu/...` identifier; transport redirects do not rename the concept.
+
+Record the taxonomy version and review date in prose when known. Do not invent a version. When a taxonomy retires a concept, retain the old link and document its replacement. A failed lookup means unavailable, not invalid or equivalent to a different result. Attribute source descriptions and observe the source's reuse terms when copying them. The reference catalog uses short descriptions written for OpenSkill and labels its mappings as publisher judgments.
+
+## OpenProfile integration
+
+An optional Skills section lists capabilities in plain language or links them to definitions:
+
+```markdown
+## Skills
+
+- [Branding](https://logicsrc.com/openskill/branding)
+- [Logo design](https://logicsrc.com/openskill/logo-design)
+- Accounting
+- [Software engineer](https://logicsrc.com/openskill/software-engineer)
+```
+
+For more detail, use a third-level heading in the same section:
+
+```markdown
+### Logo design
+
+- **Concept**: https://logicsrc.com/openskill/logo-design
+- **Level**: advanced, self-assessed
+- **Evidence**: [Selected identity projects](https://designer.example/portfolio)
+- **Last used**: 2026-09
+```
+
+The examples above are illustrative profiles. A profile can link directly to an ESCO or another vocabulary's URI without creating an OpenSkill wrapper. A linked OpenSkill record is useful when the person needs a shorter description, local scope or several mappings.
+
+Plain labels remain valid and may be offered as search suggestions. Readers keep a named concept, its source, the person's statement and any evidence separate. A profile entry is a claim. A portfolio link is evidence someone offered; it is not automatically independent verification. Levels are kept as written, including the scale and assessor when supplied. Absence does not mean beginner, expert or zero experience. Do not invent scores or translate unlike rating scales without a stated mapping.
+
+Listing an occupation does not establish a credential, a professional license, employment or permission to act for another person. Optional credentials and assessment links belong to the claimant, with issuer and scope when available. An organization listing a capability does not establish that every member has it. An agent listing one does not establish human qualifications. Hiring, access and execution remain the consuming application's decisions.
+
+OpenProfile readers that do not understand Skills retain the section under their existing unknown-section rule. No existing profile fields become required. OpenAgent's existing `skills` array remains a list of specialty labels; this convention does not change its JSON Schema or turn those strings into executable content.
+
+## Publication and portability
+
+Serve a concept at any stable URL. A conventional downloadable filename is `openskill.md`, served as `text/markdown; charset=utf-8`, without an attachment requirement. For example, `/openskill/logo-design` is the human page and `/openskill/logo-design/openskill.md` is its Markdown source. HTML pages may link to the source using `rel="alternate"` and `type="text/markdown"`.
+
+A catalog is a page or a Markdown list of links to concepts. OpenProfile's Skills section is enough for profile discovery; no account, central registry, new well-known path or executable installer is required. Relative links resolve against the source document URL. Readers retain that URL when saving locally and resolve relative links before moving the document to another origin. Public catalogs may enable CORS for browser readers. Each publisher controls the terms it serves.
+
+## Relationship to agent instructions
+
+OpenSkill is descriptive. A reader must not execute code, install tools, follow embedded instructions or grant permissions on the strength of a capability description. [Agent Skills](https://agentskills.io/specification) uses `SKILL.md` packages to give an agent procedures and resources. The formats serve different purposes and retain different names. A procedure may reference an OpenSkill concept to say what capability it helps exercise; possessing that procedure does not prove the capability.
+
+## Reference implementation
+
+The [catalog](/openskill) publishes a small set of editable Markdown concepts covering the initial design, finance and engineering examples. Each has a human page and a raw Markdown download. A [Markdown index](/openskill/catalog.md) lists the names, kinds, descriptions and source URLs in one file. The website derives both catalogs from the concept files and preserves the complete source. [/openprofile/skills](/openprofile/skills) leads to the same catalog. The catalog is a starting vocabulary, not an exhaustive ontology or an ESCO/O*NET certification service.
+
+The [logo design concept](/openskill/logo-design) links to the NicheDB identity as an example of an output. It makes no claim about a person's credentials or who should be hired. The future `w3bs.org/standards/design` page may reference these concepts when published; this draft does not claim conformance with that pending reference.
+
+## Related standards
+
+- [OpenProfile.md](/openprofile): the person, organization or agent making a capability claim.
+- [OpenResume.md](/docs/openresume): experience and work history.
+- [OpenJob](/docs/openjob): capabilities a piece of work calls for.
+- [OpenOntology](/openontology): richer provenance and governed relationships when needed.
+- [OpenAgent](/openagent): an agent's identity and advertised specialties.
+
+## License
+
+The specification and original reference descriptions are CC BY 4.0. Linked taxonomies and example artifacts keep their own terms.

docs/openskill/accountant.md

@@ -0,0 +1,30 @@
+# Accountant
+
+- **Id**: https://logicsrc.com/openskill/accountant
+- **Kind**: occupation
+- **Domain**: Finance
+- **Language**: en
+- **Aliases**: accounting professional
+
+A role concerned with maintaining, examining and explaining an organization's financial records.
+
+## Includes
+
+- Recording and reconciling financial activity and preparing reports.
+- Applying the reporting framework relevant to the work; credentials and jurisdiction belong to the individual's profile.
+
+## Related
+
+- [Accounting](https://logicsrc.com/openskill/accounting)
+- [Financial advisor](https://logicsrc.com/openskill/financial-advisor)
+
+## Taxonomy
+
+- **Broader match**: [O*NET: Accountants and Auditors](https://www.onetonline.org/link/summary/13-2011.00)
+
+This relationship is a mapping proposed by the OpenSkill publisher. The source concept was reviewed on 2026-09-13; no taxonomy release is asserted.
+
+## License
+
+Original description: CC BY 4.0, Profullstack, Inc. Linked taxonomies and example artifacts retain their own terms.
+

docs/openskill/accounting.md

@@ -0,0 +1,29 @@
+# Accounting
+
+- **Id**: https://logicsrc.com/openskill/accounting
+- **Kind**: knowledge
+- **Domain**: Finance
+- **Language**: en
+- **Aliases**: accounting principles
+
+Knowledge of how financial activity is recorded, classified, reconciled and reported.
+
+## Includes
+
+- Transactions, ledgers, reporting concepts and the relationships between financial statements.
+- The distinction between a subject someone understands and a role or credential they hold.
+
+## Related
+
+- [Accountant](https://logicsrc.com/openskill/accountant)
+
+## Taxonomy
+
+- **Close match**: [ESCO: accounting](http://data.europa.eu/esco/skill/ecc18804-a466-40d9-98b4-fba5cd67dd4b)
+
+This relationship is a mapping proposed by the OpenSkill publisher. The source concept was reviewed on 2026-09-13; no taxonomy release is asserted.
+
+## License
+
+Original description: CC BY 4.0, Profullstack, Inc. Linked taxonomies and example artifacts retain their own terms.
+

docs/openskill/branding.md

@@ -0,0 +1,30 @@
+# Branding
+
+- **Id**: https://logicsrc.com/openskill/branding
+- **Kind**: skill
+- **Domain**: Design
+- **Language**: en
+- **Aliases**: brand development, brand identity
+
+Develop a coherent identity and positioning that help people recognize and understand a person, organization or product.
+
+## Includes
+
+- Audience and positioning research.
+- Visual and verbal identity, consistent applications and brand guidelines.
+
+## Related
+
+- [Logo design](https://logicsrc.com/openskill/logo-design)
+- [Graphic design](https://logicsrc.com/openskill/graphic-design)
+
+## Taxonomy
+
+- **Narrower match**: [ESCO: define brand identity](http://data.europa.eu/esco/skill/754690ad-6207-4e1c-9df7-9a2b58afa587)
+
+This relationship is a mapping proposed by the OpenSkill publisher. The source concept was reviewed on 2026-09-13; no taxonomy release is asserted.
+
+## License
+
+Original description: CC BY 4.0, Profullstack, Inc. Linked taxonomies and example artifacts retain their own terms.
+

docs/openskill/computer-science.md

@@ -0,0 +1,30 @@
+# Computer science
+
+- **Id**: https://logicsrc.com/openskill/computer-science
+- **Kind**: knowledge
+- **Domain**: Computing
+- **Language**: en
+- **Aliases**: computing science
+
+Study of computation and information, including algorithms, representations, languages and computational systems.
+
+## Includes
+
+- Foundations of computation and the structures used to represent and process information.
+- Theoretical and practical reasoning about computational systems.
+
+## Related
+
+- [Software development](https://logicsrc.com/openskill/software-development)
+- [Software engineer](https://logicsrc.com/openskill/software-engineer)
+
+## Taxonomy
+
+- **Close match**: [ESCO: computer science](http://data.europa.eu/esco/skill/7b5cce4d-c7fe-4119-b48f-70aa05391787)
+
+This relationship is a mapping proposed by the OpenSkill publisher. The source concept was reviewed on 2026-09-13; no taxonomy release is asserted.
+
+## License
+
+Original description: CC BY 4.0, Profullstack, Inc. Linked taxonomies and example artifacts retain their own terms.
+

docs/openskill/developer.md

@@ -0,0 +1,30 @@
+# Developer
+
+- **Id**: https://logicsrc.com/openskill/developer
+- **Kind**: occupation
+- **Domain**: Computing
+- **Language**: en
+- **Aliases**: software developer, application developer
+
+A software-focused role that builds and maintains applications, services or other software systems.
+
+## Includes
+
+- Implementing and maintaining software in collaboration with its users and other contributors.
+- Here the label means software developer; property and business development are separate concepts.
+
+## Related
+
+- [Software development](https://logicsrc.com/openskill/software-development)
+- [Software engineer](https://logicsrc.com/openskill/software-engineer)
+
+## Taxonomy
+
+- **Close match**: [O*NET: Software Developers](https://www.onetonline.org/link/summary/15-1252.00)
+
+This relationship is a mapping proposed by the OpenSkill publisher. The source concept was reviewed on 2026-09-13; no taxonomy release is asserted.
+
+## License
+
+Original description: CC BY 4.0, Profullstack, Inc. Linked taxonomies and example artifacts retain their own terms.
+

docs/openskill/financial-advisor.md

@@ -0,0 +1,30 @@
+# Financial advisor
+
+- **Id**: https://logicsrc.com/openskill/financial-advisor
+- **Kind**: occupation
+- **Domain**: Finance
+- **Language**: en
+- **Aliases**: financial adviser, personal financial advisor
+
+A role that helps clients understand their financial position and plan toward their financial objectives.
+
+## Includes
+
+- Considering goals, resources, uncertainty and competing financial priorities.
+- Explaining recommendations and the assumptions and constraints behind them.
+
+## Related
+
+- [Investing](https://logicsrc.com/openskill/investing)
+- [Accountant](https://logicsrc.com/openskill/accountant)
+
+## Taxonomy
+
+- **Close match**: [O*NET: Personal Financial Advisors](https://www.onetonline.org/link/summary/13-2052.00)
+
+This relationship is a mapping proposed by the OpenSkill publisher. The source concept was reviewed on 2026-09-13; no taxonomy release is asserted.
+
+## License
+
+Original description: CC BY 4.0, Profullstack, Inc. Linked taxonomies and example artifacts retain their own terms.
+

docs/openskill/graphic-design.md

@@ -0,0 +1,30 @@
+# Graphic design
+
+- **Id**: https://logicsrc.com/openskill/graphic-design
+- **Kind**: skill
+- **Domain**: Design
+- **Language**: en
+- **Aliases**: visual communication design
+
+Communicate ideas through the arrangement of type, images, shapes and space.
+
+## Includes
+
+- Composition, hierarchy and visual communication.
+- Preparing artwork for its intended print or digital medium.
+
+## Related
+
+- [Branding](https://logicsrc.com/openskill/branding)
+- [Logo design](https://logicsrc.com/openskill/logo-design)
+
+## Taxonomy
+
+- **Close match**: [ESCO: design graphics](http://data.europa.eu/esco/skill/f058bf62-70d1-4f5e-be2a-8b26fac24a96)
+
+This relationship is a mapping proposed by the OpenSkill publisher. The source concept was reviewed on 2026-09-13; no taxonomy release is asserted.
+
+## License
+
+Original description: CC BY 4.0, Profullstack, Inc. Linked taxonomies and example artifacts retain their own terms.
+

docs/openskill/hardware-architect.md

@@ -0,0 +1,30 @@
+# Hardware architect
+
+- **Id**: https://logicsrc.com/openskill/hardware-architect
+- **Kind**: occupation
+- **Domain**: Computing
+- **Language**: en
+- **Aliases**: computer hardware architect, hardware systems architect
+
+A role that defines a computing system's hardware structure and the tradeoffs between its components.
+
+## Includes
+
+- Architecture requirements, component boundaries and interfaces.
+- Reasoning about performance, power, cost, manufacturability and verification.
+
+## Related
+
+- [Hardware architectures](https://logicsrc.com/openskill/hardware-architectures)
+- [Software engineer](https://logicsrc.com/openskill/software-engineer)
+
+## Taxonomy
+
+- **Broader match**: [O*NET: Computer Hardware Engineers](https://www.onetonline.org/link/summary/17-2061.00)
+
+This relationship is a mapping proposed by the OpenSkill publisher. The source concept was reviewed on 2026-09-13; no taxonomy release is asserted.
+
+## License
+
+Original description: CC BY 4.0, Profullstack, Inc. Linked taxonomies and example artifacts retain their own terms.
+

docs/openskill/hardware-architectures.md

@@ -0,0 +1,30 @@
+# Hardware architectures
+
+- **Id**: https://logicsrc.com/openskill/hardware-architectures
+- **Kind**: knowledge
+- **Domain**: Computing
+- **Language**: en
+- **Aliases**: computer hardware architecture
+
+Knowledge of how physical computing components are organized and connected to form a system.
+
+## Includes
+
+- Processors, memory, interconnects and component interfaces.
+- Performance, power, reliability and physical design constraints.
+
+## Related
+
+- [Hardware architect](https://logicsrc.com/openskill/hardware-architect)
+- [Computer science](https://logicsrc.com/openskill/computer-science)
+
+## Taxonomy
+
+- **Close match**: [ESCO: hardware architectures](http://data.europa.eu/esco/skill/e043aeeb-78f5-4049-afbf-12bba52225bc)
+
+This relationship is a mapping proposed by the OpenSkill publisher. The source concept was reviewed on 2026-09-13; no taxonomy release is asserted.
+
+## License
+
+Original description: CC BY 4.0, Profullstack, Inc. Linked taxonomies and example artifacts retain their own terms.
+

docs/openskill/investing.md

@@ -0,0 +1,30 @@
+# Investing
+
+- **Id**: https://logicsrc.com/openskill/investing
+- **Kind**: skill
+- **Domain**: Finance
+- **Language**: en
+- **Aliases**: investment analysis, capital allocation
+
+Evaluate opportunities and allocate capital in relation to objectives, uncertainty and a time horizon.
+
+## Includes
+
+- Research, valuation, risk assessment and portfolio reasoning.
+- Monitoring outcomes and explaining the assumptions behind an allocation.
+
+## Related
+
+- [Investor](https://logicsrc.com/openskill/investor)
+- [Financial advisor](https://logicsrc.com/openskill/financial-advisor)
+
+## Taxonomy
+
+- **Related match**: [ESCO: make investment decisions](http://data.europa.eu/esco/skill/0c9da986-721e-4f75-b566-0c6c212a8f60)
+
+This relationship is a mapping proposed by the OpenSkill publisher. The source concept was reviewed on 2026-09-13; no taxonomy release is asserted.
+
+## License
+
+Original description: CC BY 4.0, Profullstack, Inc. Linked taxonomies and example artifacts retain their own terms.
+

docs/openskill/investor.md

@@ -0,0 +1,28 @@
+# Investor
+
+- **Id**: https://logicsrc.com/openskill/investor
+- **Kind**: occupation
+- **Domain**: Finance
+- **Language**: en
+- **Aliases**: capital investor
+
+A role that commits and manages capital in assets or ventures with an expectation of future value.
+
+## Includes
+
+- Evaluating opportunities, deciding allocations and monitoring holdings.
+- The role may be personal or professional; the label alone does not establish employment or an advisory service.
+
+## Related
+
+- [Investing](https://logicsrc.com/openskill/investing)
+- [Financial advisor](https://logicsrc.com/openskill/financial-advisor)
+
+## Taxonomy
+
+No external equivalence is asserted for this local role. The linked Investing concept describes an associated capability.
+
+## License
+
+Original description: CC BY 4.0, Profullstack, Inc. Linked taxonomies and example artifacts retain their own terms.
+

docs/openskill/logo-design.md

@@ -0,0 +1,35 @@
+# Logo design
+
+- **Id**: https://logicsrc.com/openskill/logo-design
+- **Kind**: skill
+- **Domain**: Design
+- **Language**: en
+- **Aliases**: logos, logo creation, logo development
+
+Create a recognizable visual mark that identifies a person, organization or product.
+
+## Includes
+
+- Concept development, typography, geometry and optical balance.
+- Editable vector artwork, monochrome variants and small-size readability.
+
+## Related
+
+- [Branding](https://logicsrc.com/openskill/branding)
+- [Graphic design](https://logicsrc.com/openskill/graphic-design)
+
+## Taxonomy
+
+- **Broader match**: [ESCO: design graphics](http://data.europa.eu/esco/skill/f058bf62-70d1-4f5e-be2a-8b26fac24a96)
+
+This relationship is a mapping proposed by the OpenSkill publisher. The source concept was reviewed on 2026-09-13; no taxonomy release is asserted.
+
+## Examples
+
+- [NicheDB logo](https://nichedb.dev/logo.svg): a connected N identity delivered as SVG.
+- [Editable source and project brief](https://github.com/profullstack/niche-db/tree/00b808215d56c9c492ee92a5f62654b32974f023/brand): the concrete deliverable and its design constraints. This is an example of an output, not an assessment of a person's competence.
+
+## License
+
+Original description: CC BY 4.0, Profullstack, Inc. Linked taxonomies and example artifacts retain their own terms.
+

docs/openskill/software-development.md

@@ -0,0 +1,31 @@
+# Software development
+
+- **Id**: https://logicsrc.com/openskill/software-development
+- **Kind**: skill
+- **Domain**: Computing
+- **Language**: en
+- **Aliases**: programming, software implementation
+
+Turn requirements into working software and maintain its behavior as needs and operating conditions change.
+
+## Includes
+
+- Implementation, debugging, testing and maintenance.
+- Communicating tradeoffs and working with existing code and interfaces.
+
+## Related
+
+- [Developer](https://logicsrc.com/openskill/developer)
+- [Software engineer](https://logicsrc.com/openskill/software-engineer)
+- [Computer science](https://logicsrc.com/openskill/computer-science)
+
+## Taxonomy
+
+- **Related match**: [O*NET: Software Developers](https://www.onetonline.org/link/summary/15-1252.00)
+
+This relationship is a mapping proposed by the OpenSkill publisher. The source concept was reviewed on 2026-09-13; no taxonomy release is asserted.
+
+## License
+
+Original description: CC BY 4.0, Profullstack, Inc. Linked taxonomies and example artifacts retain their own terms.
+

docs/openskill/software-engineer.md

@@ -0,0 +1,31 @@
+# Software engineer
+
+- **Id**: https://logicsrc.com/openskill/software-engineer
+- **Kind**: occupation
+- **Domain**: Computing
+- **Language**: en
+- **Aliases**: software engineering professional
+
+A role that applies engineering judgment to the design, implementation, verification and evolution of software systems.
+
+## Includes
+
+- System design, software quality, operational constraints and lifecycle tradeoffs.
+- Programming and collaboration across the system's requirements and interfaces.
+
+## Related
+
+- [Developer](https://logicsrc.com/openskill/developer)
+- [Software development](https://logicsrc.com/openskill/software-development)
+- [Computer science](https://logicsrc.com/openskill/computer-science)
+
+## Taxonomy
+
+- **Close match**: [O*NET: Software Developers](https://www.onetonline.org/link/summary/15-1252.00)
+
+This relationship is a mapping proposed by the OpenSkill publisher. The source concept was reviewed on 2026-09-13; no taxonomy release is asserted.
+
+## License
+
+Original description: CC BY 4.0, Profullstack, Inc. Linked taxonomies and example artifacts retain their own terms.
+