abstractskill 0.3.0__tar.gz → 0.3.2__tar.gz

{abstractskill-0.3.0/src/abstractskill.egg-info → abstractskill-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: abstractskill
-Version: 0.3.0
+Version: 0.3.2
 Summary: Agent Skills (SKILL.md) parsing, discovery, trust gating, and demand derivation for AbstractFramework
 Author-email: Laurent-Philippe Albou <contact@abstractcore.ai>
 License-Expression: MIT

{abstractskill-0.3.0 → abstractskill-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "abstractskill"
-version = "0.3.0"
+version = "0.3.2"
 description = "Agent Skills (SKILL.md) parsing, discovery, trust gating, and demand derivation for AbstractFramework"
 readme = "README.md"
 requires-python = ">=3.10"

{abstractskill-0.3.0 → abstractskill-0.3.2}/src/abstractskill/__init__.py

@@ -140,4 +140,4 @@ __all__ = [
     "validate_skill_name",
 ]
 
-__version__ = "0.3.0"
+__version__ = "0.3.2"

{abstractskill-0.3.0 → abstractskill-0.3.2}/src/abstractskill/registry/catalog.yaml

@@ -16,7 +16,7 @@
 # four yaml files shipped in the abstractskill wheel). Bump it whenever any
 # of that content changes; seed_registry() records it in <dest>/.seeded.json
 # and tests/test_bundled.py pins it to a content digest.
-version: "2026.09.25"
+version: "2026.10.21"
 
 skills:
 

{abstractskill-0.3.0 → abstractskill-0.3.2}/src/abstractskill/registry/skills/coredoc/SKILL.md

@@ -1,13 +1,15 @@
 ---
 name: coredoc
-description: Create, audit, normalize, and maintain a professional external-facing repository documentation system for users, contributors, and tools, including the core doc set, cross-linked topic deep dives, and faithful AI-readable `llms.txt` and `llms-full.txt` files. Use when Codex needs to bootstrap docs for a new repo, repair stale or missing project docs, add or revise `docs/*.md` pages, keep root and `docs/` documents coherent, or regenerate AI-actionable documentation indexes for LLMs and tooling.
+description: Create, audit, normalize, and maintain a professional external-facing repository documentation system for users, contributors, and tools, including the core doc set, cross-linked topic deep dives, faithful AI-readable `llms.txt` and `llms-full.txt` files, and, when the package is something an agent can operate, a package agent skill at `skills/<name>/SKILL.md` that teaches other agents to use it. Use when Codex needs to bootstrap docs for a new repo, repair stale or missing project docs, add or revise `docs/*.md` pages, keep root and `docs/` documents coherent, regenerate AI-actionable documentation indexes for LLMs and tooling, or create and maintain the agent skill that lets other agents use the package like experts.
 ---
 
 # Core Doc
 
 Use this skill to make a repository explain itself clearly to external users, contributors, and
 tools. Core docs should teach what the package is, how it works, how to use it, and what current
-limits matter. Write in a professional, positive tone that addresses external readers directly.
+limits matter. When the package is something an agent can operate, the docs also ship an agent
+skill that turns them into an operating procedure for other agents. Write in a professional,
+positive tone that addresses external readers directly.
 Prefer faithful, maintainable docs over aspirational prose. If the code and docs disagree, the
 code wins and the docs must be repaired.
 
@@ -19,6 +21,8 @@ code wins and the docs must be repaired.
   `references/core-doc-set.md`.
 - If the task is mainly about creating or repairing `llms.txt` or `llms-full.txt`, read
   `references/llms-files.md` before editing.
+- On every pass, read `references/agent-skill.md` to decide whether the repository ships a
+  package agent skill, and to create, audit, or update it.
 - If the task is broad documentation maintenance, read
   `references/maintenance-playbook.md` and work through the audit flow.
 - If the user is preparing or publishing a specific release, prefer the `release` skill when
@@ -59,11 +63,11 @@ code wins and the docs must be repaired.
   measured, and what limits still matter.
 - Every core documentation page must answer stable user or contributor needs, not internal
   incidents. This applies to `README.md`, `CHANGELOG.md`, root policy docs, `docs/*.md`,
-  `docs/examples/*.md`, `llms.txt`, and `llms-full.txt`, not only FAQ pages. Do not add headings,
-  callouts, notes, tables, captions, changelog entries, or example prose like "Why did our previous
-  result...", "What went wrong...", "we discovered...", or "this failed before..." to end-user
-  docs. Convert them into neutral usage guidance such as "How to compare memory measurements" or
-  put the analysis in backlog, ADRs, reports, or `untracked/comments/`.
+  `docs/examples/*.md`, `llms.txt`, `llms-full.txt`, and `skills/<name>/`, not only FAQ pages. Do
+  not add headings, callouts, notes, tables, captions, changelog entries, or example prose like "Why
+  did our previous result...", "What went wrong...", "we discovered...", or "this failed before..."
+  to end-user docs. Convert them into neutral usage guidance such as "How to compare memory
+  measurements" or put the analysis in backlog, ADRs, reports, or `untracked/comments/`.
 - Benchmark, quantization, and performance docs may include exact settings, hardware, command
   profiles, and metric definitions. They must not include personal commentary, blame, forensic
   narratives, release-gate drama, or explanations of documentation mistakes. If unrelated benchmark
@@ -73,7 +77,7 @@ code wins and the docs must be repaired.
   smoke-test instructions, "real model caveat" blocks, debugging narratives, or notes about how
   the documentation was generated. If that information matters only to the owner, maintainer, or
   developer, write it in `untracked/comments/<timestamp>_<topic>.md` instead, and keep it out of
-  `README.md`, `CHANGELOG.md`, `docs/*.md`, `llms.txt`, and `llms-full.txt`.
+  `README.md`, `CHANGELOG.md`, `docs/*.md`, `llms.txt`, `llms-full.txt`, and `skills/<name>/`.
 - Keep the core doc set present even when a section is currently thin. If a doc is not yet
   applicable, say so explicitly instead of omitting it.
 - `docs/architecture.md` MUST contain at least one diagram that represents the system
@@ -104,10 +108,10 @@ code wins and the docs must be repaired.
 - Verify claims against repository evidence where possible: manifests, package metadata, entry
   points, CLI help, config files, schemas, examples, tests, and working commands.
 - Before finishing any core-doc update, scan the external-facing corpus (`README.md`,
-  `CHANGELOG.md`, root policy docs, `docs/*.md`, `docs/examples/*.md`, `llms.txt`, and
-  `llms-full.txt`) for incident/postmortem language, including headings, callouts, table notes,
-  image captions, changelog bullets, and examples. Remove or move anything that reads as maintainer
-  memory rather than user guidance.
+  `CHANGELOG.md`, root policy docs, `docs/*.md`, `docs/examples/*.md`, `llms.txt`, `llms-full.txt`,
+  and the package agent skill) for incident/postmortem language, including headings, callouts, table
+  notes, image captions, changelog bullets, and examples. Remove or move anything that reads as
+  maintainer memory rather than user guidance.
 
 ## Maintain The Core Set
 
@@ -129,6 +133,9 @@ code wins and the docs must be repaired.
   starter set or the repo is clearly internal and intentionally minimal.
 - For an existing project, normalize missing or stale files incrementally instead of rewriting
   everything at once.
+- The package agent skill (`skills/<name>/SKILL.md`) is conditional, not part of the
+  always-present set. Create it only when the package passes the decision in
+  `references/agent-skill.md`.
 
 ## Maintain `llms.txt` And `llms-full.txt`
 
@@ -158,6 +165,24 @@ code wins and the docs must be repaired.
   caveats must live in the real docs first.
 - Follow the format and usage notes in `references/llms-files.md`.
 
+## Maintain The Package Agent Skill
+
+- On every pass, make the agent-skill decision in `references/agent-skill.md` from repository
+  evidence, and state it with its evidence in your final report. Ship a skill when the repository
+  contains something an agent can operate and an agent with only the README would likely misuse
+  it. No skill is the default: never create one for documentation, content, or GUI-only
+  repositories, where reading the docs is the whole use.
+- The skill lives at `skills/<name>/SKILL.md` and teaches agents to use the package, not to
+  develop it: its limits, the settings and defaults that cost time or money, its error contract,
+  a capability map (what exists, what does not, what it writes), an end-to-end workflow, verified
+  recipes, sharp edges, and failure fixes. It must work with no link reachable.
+- Keep it faithful: every fact the skill states is also in the docs (when docs and code disagree,
+  fix the docs; mark defects as known issues), every snippet is verified at the highest safe
+  tier in an isolated run (never write or paid calls against a deployment you do not own), and it
+  changes in the same change as the API, CLI, or doc edits it describes.
+- When the skill exists, `README.md` gets a "For AI agents" section inviting agents to register and
+  use it to become experts on the package, and `docs/README.md` and `llms.txt` link to it.
+
 ## Add Deep Dives When Relevant
 
 - Create `docs/<topic>.md` when a topic is too important or too detailed to live only inside
@@ -175,3 +200,5 @@ code wins and the docs must be repaired.
 - Read `references/core-doc-set.md` when creating or repairing the canonical doc set.
 - Read `references/maintenance-playbook.md` when doing broad documentation audits or cleanup.
 - Read `references/llms-files.md` when creating or updating `llms.txt` or `llms-full.txt`.
+- Read `references/agent-skill.md` when deciding whether to ship a package agent skill, and when
+  creating, auditing, or updating one.

{abstractskill-0.3.0 → abstractskill-0.3.2}/src/abstractskill/registry/skills/coredoc/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Core Doc"
   short_description: "Build and maintain professional external-facing docs"
-  default_prompt: "Use $coredoc to create or maintain a professional external-facing repository documentation set, keep llms.txt files faithful, and route maintainer-only notes to untracked/comments."
+  default_prompt: "Use $coredoc to create or maintain a professional external-facing repository documentation set, keep llms.txt files faithful, create or update the package agent skill when the decision in references/agent-skill.md calls for one, and route maintainer-only notes to untracked/comments."

abstractskill-0.3.2/src/abstractskill/registry/skills/coredoc/references/agent-skill.md

@@ -0,0 +1,329 @@
+# Package Agent Skill
+
+Read this file on every coredoc pass. It decides whether the repository ships a package agent
+skill, and it governs creating, auditing, and updating one.
+
+## What It Is
+
+A package agent skill is an [Agent Skills](https://agentskills.io/) folder (`SKILL.md` plus
+optional resources) that the repository ships so that any AI agent that wants to use the package
+can load it and work like an expert user. After reading it, an agent knows when the package
+applies and where it falls short, how to install and verify it, the few concepts and settings
+that matter, the workflow an expert follows, the exact commands and code for the common tasks,
+and the mistakes to avoid.
+
+- It is a consumer artifact. It teaches how to use the package, not how to develop it. Contributor
+  workflows stay in `CONTRIBUTING.md`. Repository-local agent instructions (`AGENTS.md`,
+  `CLAUDE.md`, `.claude/skills/`, `.cursor/skills/`) serve people working on the repository and
+  are out of scope here.
+- It complements `llms.txt`: `llms.txt` helps an agent find and read the docs; the skill turns the
+  docs into an operating procedure.
+- The docs stay canonical. The skill is a faithful, task-shaped distillation of them.
+
+## Decide Whether The Repository Needs One
+
+Decide from repository evidence (the code, entry points, public exports, CLI `--help`, service
+definitions), not from README claims or self-descriptions. Re-run the decision on every pass.
+
+No skill is the default. Create one only when both conditions hold:
+
+1. The repository contains the code of at least one surface an external agent can operate (the
+   repository's own build scripts, tests, CI, and docs tooling do not count):
+   - an importable library or SDK with public exports, including a UI component library (its
+     components, hooks, and styles are a library API);
+   - a CLI that does work (console scripts, `bin` entries, a `main` module meant for users);
+   - a service interface: HTTP/REST, RPC, WebSocket, MCP server, or tool definitions;
+   - a file format, config schema, or DSL that users write and the package consumes;
+   - a plugin or extension contract that users implement.
+2. An agent given only the README would likely misuse the package or miss its main capability,
+   because correct use takes several steps, concepts that must be held together, or sharp edges
+   that fail silently.
+
+Do not create one when:
+
+- the repository is documentation, content, notes, research, or data, and reading it is the whole
+  use. A manifest counts as evidence only when this repository contains the code it builds; a
+  published docs site with a `pyproject.toml` or `package.json` is still documentation;
+- the only surface is a GUI. A CLI whose only job is to start the GUI (ports, URLs, open the
+  browser) is part of the GUI surface;
+- the entire use is one obvious command that the README quick start already shows;
+- the package has no stable entry points yet, so a skill would freeze guesses. Revisit when the
+  surface stabilizes.
+
+State the decision and its evidence in your final report for the pass (for example "Agent skill:
+created, the package exposes a Python API and the `foo` CLI" or "Agent skill: not created, the
+repository is documentation only"). Do not add tracked files that record a negative decision.
+
+Existing skills:
+
+- An existing skill whose audience is an agent operating the package (its tools, CLI, or API) is
+  the package skill, wherever it lives under `skills/`. Keep its name and structure; do not
+  reshape it to the template below. Audit it against these rules and add only what is missing.
+  If another surface also passes the decision, add a section or a `references/<surface>.md` file
+  inside it instead of creating a second skill.
+- Skills the package distributes as data for unrelated tasks (a skill registry or curated
+  collection) are product content, not the package skill. Never rewrite them under this rule.
+- If the surface an existing package skill teaches was removed, remove the skill and record the
+  removal in `CHANGELOG.md`. Otherwise maintain it; never delete it to skip the work.
+
+Scope:
+
+- In a repository with several surfaces (server, SDKs, CLI, UI), teach the surface the docs
+  recommend to external users, and route operator, contributor, and in-process surfaces to their
+  docs.
+- Default to one skill per repository. A monorepo with several packages gets one skill with a
+  `references/<package>.md` file for each package it teaches; split into separate skills only for
+  packages with unrelated audiences. Never create skills for nested repositories that this
+  repository does not track. Name a monorepo skill after the repository, not after a private
+  workspace root.
+- For a meta-package or umbrella distribution, teach profile choice, install, and health checks,
+  and route to each component's own skill or docs by absolute URL, at the component versions this
+  distribution pins. Never restate component recipes.
+
+## Location And Naming
+
+- Put the skill at `skills/<name>/SKILL.md` at the repository root. This path is
+  harness-neutral, visible on the code host, and installs as one folder copy.
+- Default `<name>` to the package's distribution name, normalized: lowercase it, drop an npm
+  `@scope/` prefix, and turn `_`, `.`, `/`, and repeated hyphens into a single `-`
+  (`AbstractRuntime` becomes `abstractruntime`). The result must use lowercase letters, digits,
+  and single hyphens, start and end with a letter or digit, be at most 64 characters, and equal
+  the folder name.
+- If a package skill already exists under another name, keep that name. Renaming breaks every
+  existing install.
+- Coredoc does not change packaging. Shipping the skill inside a wheel or npm tarball is a
+  release-engineering decision for the maintainers, so do not add it. If the project already ships
+  a copy as package data, keep that copy identical.
+
+## Layout
+
+```text
+skills/<name>/
+  SKILL.md          # required: frontmatter and the operating guide
+  references/*.md   # optional: deeper material the agent opens on demand
+  scripts/*         # optional: runnable programs, rarely needed
+```
+
+Keep `SKILL.md` under about 300 lines (roughly 3,000 to 5,000 tokens), because hosts load it whole
+when the skill activates; shorter is better. Move material the main workflow does not need (a full
+option table, an endpoint list, a schema, a second language, rare tasks) into `references/`, and
+point to each file with one line saying when to open it.
+
+The skill must work when none of its links can be reached: package hosts may be private, and
+agents often run offline. Everything a recipe needs (result shapes, limits, error codes, the
+options that matter) lives in `SKILL.md` or `references/`. Links are for going deeper.
+
+## Frontmatter
+
+```markdown
+---
+name: <name>
+description: <What the package does, in task terms.> Use when <the tasks, the import name, the CLI name, file types, or service names that should make an agent reach for it>.
+license: <the package license, for example MIT>
+compatibility: <only when needed: runtime, OS, network, server or API version, sign-in>
+metadata:
+  package-version: "<version this skill teaches>"
+---
+```
+
+- The `description` is all an agent sees before it decides to load the skill. Name the package,
+  its import or CLI names, and the concrete tasks it covers. Keep it at most 1,024 characters and
+  free of marketing language.
+- `license` keeps the terms attached when the folder is copied away from `LICENSE`.
+- Always set `metadata.package-version`: the released version of the surface the skill teaches,
+  the upcoming version when the pass prepares a release, or `unreleased` when the surface is still
+  under the changelog's Unreleased heading. Check it against `CHANGELOG.md`, and never claim a
+  release that predates the surface.
+- Use `compatibility` (at most 500 characters) for what the skill needs to work: a runtime
+  version, an operating system, network access, the server or API version a client skill needs,
+  or sign-in to a private package host.
+
+## Body
+
+For a new skill, write to the agent: imperative, terse, concrete, and faithful. Use these sections
+in this order, and leave a section out only when it would truly be empty.
+
+1. **Purpose and limits.** Two to four sentences on what the package does and when to reach for
+   it, then what it is bad at, taken from the docs' limits or FAQ, with the documented
+   alternative. An agent that does not know the limits reports wrong results with confidence.
+2. **Install and verify.** The install command, and one verify step that proves the install
+   works and prints the installed version (and, for a client, the server or API version).
+   - The install command must work in a clean environment from the source it names (check with
+     `pip index versions <dist>`, `npm view <pkg> version`, or the equivalent). If the package is
+     not published, teach the documented source install and fix the docs that say otherwise.
+   - The verify step is the first thing an agent runs in a broken environment. It passes only on
+     a real result (non-empty output, the expected version), and reports each likely failure
+     (missing configuration or credential, unreachable endpoint, failed authentication, wrong
+     version) with a clear message instead of crashing. When the version is `unreleased`, it
+     checks what identifies the surface (an API version, a feature probe), and a missing
+     identifier fails.
+   - Tell the agent to compare the installed version with `metadata.package-version`; the docs of
+     the installed version win when they disagree with the skill. When the package needs a
+     credential, tell the agent to ask the user to put it in an environment variable (never in
+     the conversation), to pass it explicitly where the package could send an ambient one to the
+     wrong host, and to stop at the first authentication failure.
+3. **Mental model.** Three to seven bullets naming the concepts, objects, or resources an agent
+   must hold to reason about the package, and how they relate. Name the settings the user docs
+   present as a cost, time, or quality trade-off (a mode, tier, level, or model choice) and when
+   to pick each value, and the defaults that silently cost time or money, with their values
+   (timeouts, automatic retries, background downloads). State the package-wide error contract
+   once here (which exceptions or error results callers must handle, and where it differs by
+   backend), so recipes can rely on it.
+4. **Capability map.** One line per major capability, with its entry point (function, class,
+   command, or endpoint) and where the skill or its `references/` teach it, covering at least
+   everything the README presents. Then the capabilities users commonly expect that the package
+   does not have (for example "no built-in provider fallback: wrap calls yourself"), and its side
+   effects: files, caches, or configuration it writes, and network calls it makes. An agent should
+   never need to search the package to learn whether something exists.
+5. **Recipes.** Start with the end-to-end workflow an expert follows for the package's main job,
+   then the single tasks, ordered by how often users perform them in the package's main job (not
+   by how many doc examples a feature has). Teach tasks, not a tour of the API: rare calls go to
+   `references/`. For each recipe, give:
+   - a one-line goal;
+   - the minimal code or command, complete on its own with imports and real names (or starting
+     with a comment naming the recipe it continues), with clearly marked placeholders such as
+     `<MODEL_NAME>`, quoted in shell snippets;
+   - handling of the failure and empty cases specific to the task (a failed status, an optional
+     field that can be missing, an empty result, an unknown event type), relying on the error
+     contract from the mental model for the rest;
+   - what success looks like (output, return type, file produced), and the one or two options
+     that change the result.
+6. **Rules and sharp edges.** When calls cost money, take minutes, or change shared state, open
+   this section with them: which calls, the cheap way to answer first, and what to confirm with
+   the user. Then invariants and the mistakes an agent is most likely to make (wrong identifier,
+   wrong call order, wrong default, silent failures, credentials sent where they should not go),
+   each with how to avoid it. State each fact once in the skill; refer back instead of repeating.
+7. **When things fail.** The three to five most common error messages or symptoms, each with
+   cause and fix. Link to the troubleshooting page for the rest.
+8. **Go deeper.** Absolute links to the docs (getting started, API reference, troubleshooting,
+   `llms-full.txt`) and to the skill's own `references/` files, each with one line saying when to
+   open it.
+
+## Code: Snippets And Scripts
+
+Code is how the skill turns knowledge into competence. Include it whenever the package has a
+programmatic surface.
+
+- Default to fenced snippets inside recipes. Each snippet must run as written once its marked
+  placeholders are filled.
+- Add a file under `scripts/` only when the code would exceed about 30 lines as a snippet or must
+  run unattended, and the package provides no equivalent command in the environment the agent will
+  have. Hosts that gate skills by trust (AbstractSkill among them) treat files under `scripts/` and
+  code files anywhere in the folder as scripts and require review before activation, so a script
+  must be worth that cost.
+- Every script must be self-contained (the package and the standard library only), start with a
+  header comment saying what it does and how to run it, read credentials only from environment
+  variables, be safe by default (no destructive, paid, or remote calls unless behind an explicit
+  argument), stay small and limited to the public API, and be referenced from `SKILL.md` with its
+  exact run command relative to the skill folder.
+
+## Faithfulness And Verification
+
+Facts:
+
+- Names, signatures, and field types may come from the public code. Behaviors, defaults, limits,
+  error codes, timings, and the result shapes a recipe branches on must be in the docs: before
+  finishing, list them and add any that the docs lack, in the same change. Never let the skill be
+  the only place a fact lives, and keep the docs' qualifiers ("a soft target of 30 s" must not
+  become "30 s").
+- When the docs and the code disagree, the code wins: fix the docs. A fact several pages need is
+  stated once and linked from the others; fix every page that restates it. If a docstring is
+  stale, report it; do not edit code.
+- When verification shows behavior that looks like a defect (an error that escapes the documented
+  contract, input silently ignored, a crash), do not document it as intended. Keep the documented
+  contract and add one line next to it ("Known issue (<version>): <behavior>. Workaround:
+  <workaround>."); that line is the doc source for the workaround the skill teaches. Test the
+  workaround on the exact calls the recipe makes, and list the defect with a reproduction in the
+  pass report.
+- When the package fronts several backends (providers, engines, databases, platforms), find its
+  distinct code paths (from the class hierarchy or dispatch code), list them in the pass report,
+  verify each claim on one backend per path, and label backend-specific behavior as such. Never
+  generalize one backend's behavior to the rest.
+- Teach what every user of the package meets, never facts from your own pass: your credentials,
+  your deployment, or problems you hit while verifying belong in the pass report.
+- Use only the public, documented API.
+
+Running what you publish:
+
+- Run every snippet and script at the highest tier you can reach safely, and record the tier in
+  the pass report: (1) live, with read-only calls only, labeled "1 (stand-in: <server>)" when a
+  local server speaking the same protocol stands in for the real service; (2) through the real
+  package against the repository's own recorded fixtures or test server; (3) checked against
+  code and tests, or run against a mock you built, which proves names and signatures, not
+  behavior. A snippet's tier is the lowest tier of the calls it depends on, given per backend for
+  backend-neutral snippets.
+- Run the failure cases the skill names, plus one unreachable-endpoint run per backend code path.
+  A snippet that crashes there, or reports success on an empty or truncated result, is wrong even
+  if the docs show it: fix both.
+- Never run write, delete, or paid calls against a deployment you do not own. Stop at the first
+  authentication failure, never retry a login, and test authentication failures only by sending
+  no credential, never an invented, old, or borrowed one.
+- Isolate the run: unset real credentials, point configuration at a scratch directory (for
+  example a temporary `HOME`), and point the client base-URL variables at a closed loopback port,
+  so a snippet without an explicit endpoint fails locally. To run a cloud client against a local
+  stand-in, pass the stand-in URL and any placeholder key as arguments in that call only, never
+  in environment variables.
+
+Maintenance:
+
+- Update the skill in the same change as the API, CLI, configuration, or doc edits it describes,
+  exactly as with `llms.txt` and `llms-full.txt`, and audit names, defaults, limits, error
+  messages, `metadata.package-version`, and links on every pass.
+- The external-facing rules of the core docs apply: no maintainer notes, no incident history, no
+  documentation-generation commentary, and no time-relative wording.
+
+## Links
+
+The skill is copied out of the repository when someone installs it, so relative links into the
+repository break.
+
+- Link to repository docs with absolute raw-file URLs that return Markdown: on GitHub
+  `https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>`, on GitLab
+  `<repository URL>/-/raw/<ref>/<path>`. Link to a hosted docs site only with page URLs you have
+  checked. When the host requires sign-in, say so in `compatibility`.
+- `<ref>` is the tag of `metadata.package-version` when that tag already contains the skill
+  folder, and otherwise the code host's default branch (`git ls-remote --symref
+  <repository URL> HEAD`, not the clone's `origin/HEAD`). Switch to the version tag in the first
+  release that ships the skill.
+- Link to the skill's own files with relative paths (`references/<file>.md`, `scripts/<file>`).
+- Check that `<ref>` contains the skill folder and every path the skill or its README snippet
+  links or installs (`git ls-tree -r --name-only <ref> -- <paths>`). If it does not yet (an
+  unmerged branch, an untagged release), still add the skill and its pointers in this change, and
+  state in the pass report that they resolve once the change reaches `<ref>`.
+
+## Point The Docs At The Skill
+
+When the skill exists, the docs must tell agents about it:
+
+- `README.md`: a short section like the one below. Use absolute URLs, because package indexes
+  such as PyPI and npm render the README away from the repository. Fill in the real repository
+  URL, `<ref>`, skill name, and skill folder URL (on GitHub
+  `<repository URL>/tree/<ref>/skills/<name>`, on GitLab
+  `<repository URL>/-/tree/<ref>/skills/<name>`). When `<ref>` already contains the skill, run the
+  snippet once.
+
+  ~~~markdown
+  ## For AI agents
+
+  If you are an AI agent, you can register and use our agent skill
+  [`<name>`](<skill folder URL>) to become an expert on this package. Install it by copying the
+  `skills/<name>/` folder of the version you use into your agent's skills directory (for example
+  `~/.claude/skills` for Claude Code; see your agent's documentation for its skills directory):
+
+  ```bash
+  SKILLS_DIR=~/.claude/skills
+  tmp="$(mktemp -d)"
+  git clone --depth 1 --branch <ref> <repository URL> "$tmp" \
+    && mkdir -p "$SKILLS_DIR" && cp -R "$tmp/skills/<name>" "$SKILLS_DIR/" \
+    && echo "installed: $SKILLS_DIR/<name>"
+  rm -rf "$tmp"
+  ```
+  ~~~
+
+  Update `<ref>` in the same change as `metadata.package-version`.
+- `docs/README.md`: list the skill in the index with one line on what it is for.
+- `llms.txt`: an `## Agent Skill` section linking to `SKILL.md`, as shown in
+  `references/llms-files.md`.
+- `CHANGELOG.md`: record when the skill is added, removed, or changes in a way its users notice.
+
+When there is no skill, add none of these.

{abstractskill-0.3.0 → abstractskill-0.3.2}/src/abstractskill/registry/skills/coredoc/references/core-doc-set.md

@@ -53,6 +53,13 @@ preferred baseline, not a universal law for every tiny or internal repo.
 - `llms-full.txt`
   - expanded aggregate of the core docs when this profile is adopted
 
+## Conditional Agent Skill
+
+- `skills/<name>/SKILL.md`
+  - an agent skill that teaches other AI agents to use the package, shipped only when the
+    repository passes the decision in `agent-skill.md`, which also owns its layout, content, and
+    verification rules
+
 ## Default Layout
 
 ```text
@@ -73,6 +80,11 @@ docs/
   faq.md
   troubleshooting.md
   <topic>.md
+skills/                 # only when the package passes the agent-skill decision
+  <name>/
+    SKILL.md
+    references/         # optional
+    scripts/            # optional
 ```
 
 ## Cross-Link Expectations
@@ -92,6 +104,10 @@ docs/
 - `docs/troubleshooting.md` should link back to the relevant setup, API, architecture, FAQ, or
   topic page for each symptom.
 - `CONTRIBUTING.md` should point contributors to architecture, API, changelog, and security docs.
+- When `skills/<name>/SKILL.md` exists, `README.md` should have a short "For AI agents" section
+  inviting agents to register and use the skill, and `docs/README.md` and `llms.txt` should link
+  to it. The skill links back to the docs with absolute URLs, because it is copied out of the
+  repository when installed.
 
 ## Canonical Ownership Matrix
 
@@ -112,6 +128,10 @@ docs/
     paths
 - `docs/<topic>.md`
   - owns reusable deep dives that would otherwise bloat the core docs
+- `skills/<name>/`
+  - owns the agent-facing operating procedure: task recipes, sharp edges, and runnable examples
+    distilled from the docs. It owns no facts of its own; every behavior it states must also be in
+    the docs or the code
 
 Backlog, ADRs, reports, and incident notes own internal reasoning history, rejected approaches,
 postmortems, and root-cause narratives. Core docs are not project memory. They may link to ADRs or
@@ -133,7 +153,8 @@ If a file is required but a topic is currently not mature, write the truthful mi
 
 ## Front-Facing Content Filter
 
-Before adding a sentence to `README.md`, `docs/*.md`, `llms.txt`, or `llms-full.txt`, ask whether an
+Before adding a sentence to `README.md`, `docs/*.md`, `llms.txt`, `llms-full.txt`, or the agent
+skill, ask whether an
 external user, contributor, or tool needs it to understand what the package is, how it works, how to
 install it, how to use it, how to configure it, how to debug it, how to migrate, or how to
 contribute.

{abstractskill-0.3.0 → abstractskill-0.3.2}/src/abstractskill/registry/skills/coredoc/references/llms-files.md

@@ -62,6 +62,9 @@ Optional guidance paragraphs.
 ## Topic Deep Dives
 - [docs/<topic>.md](docs/<topic>.md): why this topic matters
 
+## Agent Skill
+- [skills/<name>/SKILL.md](skills/<name>/SKILL.md): agent skill that teaches agents to use this package
+
 ## Optional
 - [CHANGELOG.md](CHANGELOG.md): release history
 - [ACKNOWLEDGEMENTS.md](ACKNOWLEDGEMENTS.md): credits and lineage
@@ -76,6 +79,8 @@ Rules:
 - Keep the same professional, positive, external-facing tone as the tracked source docs.
 - Do not include maintainer-only notes, internal validation commands, or content copied from
   `untracked/comments/`.
+- Include the `Agent Skill` section only when `skills/<name>/SKILL.md` exists. See
+  `agent-skill.md`.
 
 ## `llms-full.txt` Requirements
 
@@ -114,6 +119,9 @@ Rules:
 - Do not aggregate maintainer-only notes from `untracked/comments/`, internal smoke-test blocks, or
   documentation-generation commentary.
 - Prefer document separators so tools and humans can navigate the aggregate.
+- Do not aggregate the agent skill. It is distilled from the docs that `llms-full.txt` already
+  contains. Agents reach it through the `Agent Skill` entry in `llms.txt` and through the "For AI
+  agents" section of the aggregated `README.md`.
 - Keep duplicated content low; if two docs repeat heavily, consolidate the real docs first.
 - Do not blindly concatenate huge, repetitive, or sensitive material. Link out when a bounded
   aggregate is more useful than a giant dump.
@@ -128,7 +136,7 @@ Rules:
   topic deep dives included by the file.
 - If a doc says a feature is absent or unstable, `llms.txt` and `llms-full.txt` must say the same.
 - If an API, CLI, or integration changed, update the core docs together with the LLM index
-  files in the same change.
+  files, and the agent skill when one exists, in the same change.
 - If the source docs intentionally omit internal mistake history, do not reintroduce that history
   in the LLM index files.
 - If maintainers need extra internal guidance, keep it in `untracked/comments/<timestamp>_<topic>.md`

{abstractskill-0.3.0 → abstractskill-0.3.2}/src/abstractskill/registry/skills/coredoc/references/maintenance-playbook.md

@@ -19,13 +19,15 @@ Use this file for broad repository documentation work.
    - broken links;
    - orphan `docs/<topic>.md` pages;
    - missing `llms.txt` / `llms-full.txt`;
+   - a missing agent skill for a package with an actionable surface, a stale one (renamed calls,
+     changed flags, broken links), or one that should not exist (see `agent-skill.md`);
    - docs that should exist but are crammed into README only.
 5. Fix the highest-value inconsistencies first:
    - installation and first-run instructions;
    - missing or stale troubleshooting for common user-facing failures;
    - architecture or API drift;
    - missing contributor/security/license basics;
-   - broken AI-readable indexes.
+   - broken AI-readable indexes and stale agent skill recipes.
 
 ## Writing Rules
 
@@ -96,6 +98,8 @@ need it to interpret logs, migration impact, or compatibility boundaries.
 - `docs/README.md` lists every topic deep dive with a short explanation.
 - `README.md` points readers into the docs tree.
 - `llms.txt` and `llms-full.txt` match the current docs corpus.
+- The agent-skill decision was made from repository evidence and stated in the final report. When
+  the skill exists, it follows `agent-skill.md` and its verification tiers are in the report.
 - Links resolve and point to the canonical target.
 - Front-facing docs do not contain internal mistake narratives. Changelog entries, when needed,
   state only user-visible changes and migration impact.
@@ -112,6 +116,10 @@ need it to interpret logs, migration impact, or compatibility boundaries.
   troubleshooting page.
 - `llms.txt` lists docs that no longer exist or no longer matter.
 - `llms-full.txt` contains stale or duplicated material instead of a faithful aggregate.
+- the agent skill tours the API instead of teaching a workflow, omits the package's limits, ships
+  snippets that crash on failure cases, or depends on links that are unreachable once installed.
+- an agent skill is created for a documentation-only repository, or teaches contributing instead
+  of using the package.
 - topic docs include ephemeral repair commentary instead of stable current behavior.
 - generated docs leak maintainer-only notes, test recipes, or internal caveats into external
   documentation.

{abstractskill-0.3.0 → abstractskill-0.3.2}/src/abstractskill/registry/validations.yaml

@@ -208,26 +208,31 @@ validations:
     CI/CD settings.'
 - name: coredoc
   source: codex-skills (maintainer)
-  tree_hash: 9e574029b99507ce2f50b0a8e792529274da8e022a87982ed0313d04e22c1bc7
+  tree_hash: 2a6d6f46cfa504f6ca2b178f9d98e193eb0f12a6099bb5a0a0b0adbf3f43a185
   level: adopted
   method: first-party-adoption
   audience: host
   validated_by: skill
-  validated_at: '2026-07-13'
+  validated_at: '2026-10-21'
   evidence:
     parser_roundtrip: true
     has_scripts: false
-    files: 5
+    files: 6
   notes: "Maintainer-authored codex skill; first-party reviewed and vendored byte-verbatim.\
     \ Field-evidence fold 2026-07-13 (agency c1679): llms freshness sharpened from\
     \ habit to invariant in SKILL.md and references/llms-files.md \u2014 regenerate\
     \ llms files in the same change that edits docs (the stale window misrepresents\
-    \ the docs). Fable5-reviewed. Behavioral audit (backlog 0003) pending \u2014 upgrades\
+    \ the docs). Operator-requested fold 2026-10-21: package agent skill (references/agent-skill.md)\
+    \ \u2014 relevance decision from repository evidence, skills/<name>/ layout, verified\
+    \ recipes, docs pointers; adversarially reviewed (two rounds) and field-trialled\
+    \ on RAGNAROK and AbstractCore (author, A/B consumer and adversary agents, four\
+    \ rounds). Fable5-reviewed. Behavioral audit (backlog 0003) pending \u2014 upgrades\
     \ to audited then."
   activation_description: Create, audit, and maintain a professional external-facing
     documentation set (README, docs/*, architecture with diagrams, llms.txt/llms-full.txt)
-    kept faithful to the code. Use when an agent must bootstrap or repair project
-    documentation.
+    kept faithful to the code and, when the package is something an agent can operate,
+    a package agent skill at skills/<name>/ that teaches other agents to use it. Use
+    when an agent must bootstrap or repair project documentation.
 - name: entity-observation
   source: first-party
   tree_hash: ab92b03566aa02fdf0835348e8f7864c1da29e7b0916ea47dc9817a6c349f7f1

{abstractskill-0.3.0 → abstractskill-0.3.2/src/abstractskill.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: abstractskill
-Version: 0.3.0
+Version: 0.3.2
 Summary: Agent Skills (SKILL.md) parsing, discovery, trust gating, and demand derivation for AbstractFramework
 Author-email: Laurent-Philippe Albou <contact@abstractcore.ai>
 License-Expression: MIT

{abstractskill-0.3.0 → abstractskill-0.3.2}/src/abstractskill.egg-info/SOURCES.txt

@@ -55,6 +55,7 @@ src/abstractskill/registry/skills/cicd/references/repository-setup.md
 src/abstractskill/registry/skills/cicd/references/workflow-patterns.md
 src/abstractskill/registry/skills/coredoc/SKILL.md
 src/abstractskill/registry/skills/coredoc/agents/openai.yaml
+src/abstractskill/registry/skills/coredoc/references/agent-skill.md
 src/abstractskill/registry/skills/coredoc/references/core-doc-set.md
 src/abstractskill/registry/skills/coredoc/references/llms-files.md
 src/abstractskill/registry/skills/coredoc/references/maintenance-playbook.md

{abstractskill-0.3.0 → abstractskill-0.3.2}/tests/test_bundled.py

@@ -38,8 +38,8 @@ LICENSES = (
 # The bundle version must move whenever the bundled content moves. When this
 # test fails: bump `version:` in src/abstractskill/registry/catalog.yaml, then
 # update BOTH values below (the digest printed in the failure message).
-PINNED_VERSION = "2026.09.25"
-PINNED_DIGEST = "61d8b95ae2c07c247b516d4a76963b49019860b292a0d68117e20122fa6f16fa"
+PINNED_VERSION = "2026.10.21"
+PINNED_DIGEST = "35418bac94def61ae3be5fa59e3ea7632fd9e8c497eb13aa5d35f9256f53d7a8"
 
 
 def _bundle_digest(root: Path) -> str: