From 8fc244ceac562f38392914a798edc918daa412ee Mon Sep 17 00:00:00 2001 From: YiJie Date: Sun, 20 Sep 2026 23:07:37 +0800 Subject: [PATCH] feat(skills): separate standard docs from user experience --- .agents/docs/README.md | 2 +- .agents/docs/install-docs-skill.md | 84 ++++++++++++-------------- README.md | 8 ++- llms.txt | 11 +++- skills/cordisx-docs/SKILL.md | 17 +++++- skills/cordisx-docs/agents/openai.yaml | 4 ++ skills/cordisx-docs/version.json | 4 ++ skills/index.md | 25 +++++--- 8 files changed, 92 insertions(+), 63 deletions(-) create mode 100644 skills/cordisx-docs/agents/openai.yaml create mode 100644 skills/cordisx-docs/version.json diff --git a/.agents/docs/README.md b/.agents/docs/README.md index 1c843d4..e176b79 100644 --- a/.agents/docs/README.md +++ b/.agents/docs/README.md @@ -4,7 +4,7 @@ These pages explain this repository's navigation and publication responsibilitie Host product guides and Protocol specifications remain at their source. - [Agent discovery entry](../../llms.txt) and [task index](../../skills/index.md). -- [Install the documentation Skill](install-docs-skill.md). +- [Skill availability and optional standalone use](install-docs-skill.md). - [Contribute and choose the source owner](contributor-guide.md). - [Current portal implementation](../../site/README.md). - [Planned aggregation boundary](../../integrations/README.md). diff --git a/.agents/docs/install-docs-skill.md b/.agents/docs/install-docs-skill.md index 3b25d5c..a707414 100644 --- a/.agents/docs/install-docs-skill.md +++ b/.agents/docs/install-docs-skill.md @@ -1,44 +1,40 @@ -# Install The CordisX Documentation Skill - -The `cordisx-docs` Skill teaches an assistant where to look when a CordisX task -arises. Its only installed file is [SKILL.md](../../skills/cordisx-docs/SKILL.md); -product documentation stays online with its owner. It is not an npm package, -runtime plugin, or replacement for `cordisx-plugin-development`. - -## Codex - -Use the user's configured Skill directory. The current documented Codex -user-level location is `$HOME/.agents/skills/cordisx-docs/SKILL.md`; see -[Codex Skill locations](https://developers.openai.com/codex/skills/). -If an older installation already discovers a copy under `$CODEX_HOME/skills` -or `$HOME/.codex/skills`, update that existing copy instead of creating a second -Skill with the same name. -Check whether that Skill already exists before downloading. Reuse an identical -copy; preserve local edits instead of overwriting them during initial setup. - -For a new installation: - -```bash -SKILL_DIR="$HOME/.agents/skills/cordisx-docs" -mkdir -p "$SKILL_DIR" -curl --fail --location https://raw.githubusercontent.com/cordisx/docs/main/skills/cordisx-docs/SKILL.md --output "$SKILL_DIR/SKILL.md" -``` - -Read the downloaded file and verify its `name: cordisx-docs` frontmatter. Use the -agent's Skill discovery/reload mechanism, or start a new session if necessary, -and verify it lists `cordisx-docs`. A successful download alone does not prove -the current session has loaded it. Do not restart the CordisX Host for this step. - -## Other Assistants Or Read-Only Use - -Use the assistant's documented Skill installer/directory for the same standalone -file. Do not guess another product's configuration path. Without Skill support, -read [the Docs entry](../../llms.txt) on demand; persistent installation is not -required to use the guides. - -## After Installation - -Ask a relevant question, such as "How do I configure a CordisX plugin source?" -The Skill should select the Marketplace route from [the index](../../skills/index.md), -not install anything or read all guides. Existing runtime plugins and their -permissions are unchanged. Remove only this Skill's directory to uninstall it. +# CordisX Skill Availability + +Describe your task to the `cordisx` entry when available. It selects standard +documentation, user-experience Q&A, or Plugin Dev without asking you to choose a +Skill. Product documentation remains online with its owning repository. + +## CordisX Startup + +The Host manages its bundled Skills during a normal launch into that launch's +effective home. A release containing the unified bundle provides `cordisx`, +`cordisx-docs`, `cordisx-qa`, and `cordisx-plugin-development`. Do not add a separate +Docs Skill download to ordinary installation or startup instructions. + +The published `0.1.0-beta.13` predates the unified bundle and provisions only +Plugin Dev. Source changes do not update an already installed CLI. Use the +documentation matching the installed release; until it includes the bundle, +the [Docs entry](../../llms.txt) works directly without Skill installation. +See the Host's [startup Q&A](https://github.com/cordisx/cordisx/blob/main/.agents/docs/startup-qa.md) +for managed files, existing user content, and home selection. + +## Optional Standalone Use + +For an assistant outside a CordisX-managed launch, use its documented Skill +installation mechanism only when persistent installation is requested. The +canonical [Docs Skill](../../skills/cordisx-docs/SKILL.md) is maintained here; +`agents/openai.yaml` supplies optional interface metadata. It is not an npm +package or runtime plugin. Read the file directly for one-off use. + +Use the user's existing Skill location and preserve local edits rather than +creating a duplicate with the same name. In Codex the user location is +`$HOME/.agents/skills`; see [Skill locations](https://developers.openai.com/codex/skills/). +Follow the assistant's discovery mechanism to check availability. A file on +disk does not prove that the current session loaded it. No CordisX restart, +plugin installation, or permission grant is needed merely to read documentation. + +## Packaging Source + +The Host bundles a snapshot from an exact Docs commit rather than downloading +mutable Skill instructions at startup. This repository owns the canonical +entry and metadata; the Host owns provisioning and snapshot provenance. diff --git a/README.md b/README.md index 1c1fd67..e25c148 100644 --- a/README.md +++ b/README.md @@ -5,11 +5,13 @@ Navigation and presentation for `https://cordisx.github.io/docs/`. ## Getting started with an AI assistant ```text -Read the CordisX documentation entry and install its documentation Skill so you can find the right guide for my CordisX requests: https://raw.githubusercontent.com/cordisx/docs/main/llms.txt +Use this guide to find the documentation for my CordisX question. + +https://raw.githubusercontent.com/cordisx/docs/main/llms.txt ``` -After installation, describe your CordisX task normally. The Skill loads relevant -owner documentation on demand. [Read the entry](llms.txt) or browse the +Describe your question normally. Read only the relevant owner documentation; +no separate Skill setup is required to use the guides. [Read the entry](llms.txt) or browse the [Skill and documentation index](skills/index.md). ## Portal ownership diff --git a/llms.txt b/llms.txt index 099f977..180684d 100644 --- a/llms.txt +++ b/llms.txt @@ -7,8 +7,12 @@ layer, not another implementation or copy of the Host and plugin manuals. 1. For first-time product setup, read [CordisX adoption](https://raw.githubusercontent.com/cordisx/cordisx/main/llms.txt). Skip setup already completed in this task. -2. To make documentation discoverable in future sessions, follow [Install the documentation Skill](.agents/docs/install-docs-skill.md). -3. For a specific question, choose the smallest relevant entry in [the Skill and documentation index](skills/index.md). +2. For a specific question, choose the smallest relevant entry in [the Skill and documentation index](skills/index.md). +3. Use the installed `cordisx` entry when available. It selects standard Docs, + user-experience Q&A, or Plugin Dev as needed. Reading this portal does not + require installing Skills; startup manages the Skills bundled by that Host + release. [Skill availability](.agents/docs/install-docs-skill.md) covers + older releases and optional standalone use. Resolve relative links against this document's URL. Read only the selected topic and its required references; do not crawl every linked page or loop back through @@ -22,3 +26,6 @@ or log into services. Follow the user's request and the target tool's permission This public portal does not contain private source addresses or credentials. Product commands and compatibility facts belong to their linked owners. Check the installed release's help/docs if current `main` differs from that release. +Keep user-facing requirements separate from repository maintenance conventions. +Practical experience belongs in Q&A, with its context and applicable limits; +standard documentation remains authoritative for product behavior. diff --git a/skills/cordisx-docs/SKILL.md b/skills/cordisx-docs/SKILL.md index cd1bce3..00f3761 100644 --- a/skills/cordisx-docs/SKILL.md +++ b/skills/cordisx-docs/SKILL.md @@ -1,6 +1,6 @@ --- name: cordisx-docs -description: Find authoritative CordisX documentation for installation, startup, profiles, Marketplace sources, plugin installation, troubleshooting, and plugin-development references. Use for CordisX questions and setup; not general Codex account or coding questions. +description: Find standard CordisX documentation for usage, configuration, supported capabilities, and versioned plugin contracts. Use when a CordisX answer or action needs an authoritative reference; practical experience belongs to cordisx-qa. --- # CordisX Documentation @@ -14,11 +14,22 @@ whole documentation set. installation merely because the user asks a question. - For an existing plugin, use the Marketplace and the user's selected source. Read that plugin's own guide for service configuration and login. -- For plugin implementation, continue with the separate plugin-development - Skill; this Skill does not duplicate its contract or workflow. +- For practical questions, workarounds, or lessons from earlier use, consult + `cordisx-qa` when available. Use the owner documentation to check any product + claims; a reported experience does not redefine the contract. +- For plugin implementation, use `cordisx-plugin-development` when available; + this Skill supplies references, not a duplicate development workflow. - If the user provides a private entry, read it only in the authorized context. Keep private URLs, source metadata, and credentials out of public files. +Read product guides, not repository maintenance rules, for end-user tasks. +Distinguish required compatibility and runtime constraints from optional advice +and first-party conventions. Do not require third-party developers to adopt +CordisX's organization scope, repository layout, approval process, or release +workflow. Consult contribution rules only when the user is contributing to that +specific repository. If a companion Skill is unavailable, follow the relevant +owner guide directly; do not make installing another Skill a prerequisite. + Resolve relative links against the containing document's URL. A prerequisite already completed need not be performed again. An inaccessible link is a missing reference, not permission to guess endpoints or commands. Documentation on `main` diff --git a/skills/cordisx-docs/agents/openai.yaml b/skills/cordisx-docs/agents/openai.yaml new file mode 100644 index 0000000..0bc36be --- /dev/null +++ b/skills/cordisx-docs/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "CordisX Docs" + short_description: "Find standard CordisX documentation" + default_prompt: "Use $cordisx-docs to find the authoritative guide for my CordisX question." diff --git a/skills/cordisx-docs/version.json b/skills/cordisx-docs/version.json new file mode 100644 index 0000000..b0800d2 --- /dev/null +++ b/skills/cordisx-docs/version.json @@ -0,0 +1,4 @@ +{ + "version": "2026-09-20.1", + "source": "https://github.com/cordisx/docs/tree/main/skills/cordisx-docs" +} diff --git a/skills/index.md b/skills/index.md index 8afeac0..8bd1bcf 100644 --- a/skills/index.md +++ b/skills/index.md @@ -3,15 +3,20 @@ Choose one route for the current task. These are links to authoritative owners, not an instruction to load every document. -| Task | Read first | Continue only when relevant | -| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | -| Install or start CordisX | [Host entry](https://raw.githubusercontent.com/cordisx/cordisx/main/llms.txt) | Its Getting started and startup Q&A links | -| Configure a Marketplace or install an existing plugin | [Marketplace entry](https://raw.githubusercontent.com/cordisx/marketplace/main/llms.txt) | The selected source's own guide and plugin README | -| Keep documentation discoverable | [Install the navigation Skill](../.agents/docs/install-docs-skill.md) | [cordisx-docs](cordisx-docs/SKILL.md) | -| Add or change a plugin's behavior | [Plugin-development Skill](https://raw.githubusercontent.com/cordisx/cordisx/main/skills/cordisx-plugin-development/SKILL.md) | Its task-specific references | -| Understand Host configuration or troubleshoot behavior | [Host documentation index](https://raw.githubusercontent.com/cordisx/cordisx/main/.agents/docs/README.md) | The owning topic, at the installed release when needed | -| Check versioned plugin contracts | [Protocol index](https://raw.githubusercontent.com/cordisx/cordisx-protocol/main/.agents/docs/README.md) | The contract version named by the package | +| Task | Read first | Continue only when relevant | +| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | +| Install or start CordisX | [Host entry](https://raw.githubusercontent.com/cordisx/cordisx/main/llms.txt) | Its Getting started and startup Q&A links | +| Configure a Marketplace or install an existing plugin | [Marketplace entry](https://raw.githubusercontent.com/cordisx/marketplace/main/llms.txt) | The selected source's own guide and plugin README | +| Start from one CordisX entry | [CordisX Skill](https://raw.githubusercontent.com/cordisx/cordisx/main/skills/cordisx/SKILL.md) | [Skill availability](../.agents/docs/install-docs-skill.md) | +| Find standard documentation | [cordisx-docs](cordisx-docs/SKILL.md) | The relevant owner guide | +| Find or record practical user experience | [Q&A Skill](https://raw.githubusercontent.com/cordisx/cordisx/main/skills/cordisx-qa/SKILL.md) | Its topic-specific user Q&A | +| Add or change a plugin's behavior | [Plugin-development Skill](https://raw.githubusercontent.com/cordisx/cordisx/main/skills/cordisx-plugin-development/SKILL.md) | Its task-specific references | +| Understand Host configuration or troubleshoot behavior | [Host documentation index](https://raw.githubusercontent.com/cordisx/cordisx/main/.agents/docs/README.md) | The owning topic, at the installed release when needed | +| Check versioned plugin contracts | [Protocol index](https://raw.githubusercontent.com/cordisx/cordisx-protocol/main/.agents/docs/README.md) | The contract version named by the package | -The navigation Skill routes reading; the development Skill guides implementation. -Neither is a CordisX runtime plugin. For a private source, use the entry supplied +The `cordisx` entry chooses among Docs, Q&A, and Plugin Dev. Users do not need to +select an internal Skill. Docs navigates standards, Q&A carries practical +experience, and Plugin Dev guides implementation. These are not CordisX runtime +plugins. The linked source may be newer than the installed release; use the +owner guides directly when a companion Skill is unavailable. For a private source, use the entry supplied by the user instead of guessing an internal URL or copying it into public docs.