Architecture

AbstractSkill is a passive contract library: it parses, validates, hashes, discovers, composes, and classifies skills. It executes nothing and imposes no runtime limits — hosts (the gateway console, the runtime activation path) consume its contracts and enforce policy.

Components

graph TD
    subgraph abstractskill
        parser[parser.py<br/>parse_skill_md]
        validation[validation.py<br/>name/description/compatibility]
        models[models.py<br/>SkillMetadata / SkillDocument]
        loader[loader.py<br/>FilesystemSkillLoader]
        hash[hash.py<br/>content_hash]
        tree[tree.py<br/>hash_skill_tree / inspect_skill_dir]
        prompt[prompt.py<br/>format_available_skills_xml]
        policy[policy.py<br/>effective_tools]
        trust[trust.py<br/>evaluate_trust + registries]
    end

    parser --> validation
    parser --> models
    parser --> hash
    loader --> parser
    loader --> models
    tree --> validation
    policy --> models
    prompt --> models

    subgraph consumers
        console[gateway console<br/>skill picker]
        runtime[runtime<br/>activation + tool gate]
    end

    loader --> console
    trust --> console
    policy --> runtime
    trust --> runtime
    prompt --> runtime

Data flow: skill selection through trust and composition

flowchart LR
    A[skill folder on disk] --> B[discover: metadata only]
    B --> C[inspect_skill_dir<br/>tree_hash + has_scripts]
    C --> D[evaluate_trust<br/>vs registries]
    D -->|blocked| E[refuse]
    D -->|requires_review| F[operator decides]
    D -->|attachable| G[load full body]
    G --> H[effective_tools<br/>grant ∩ declared]
    H --> I[format_available_skills_xml<br/>into prompt head]

Trust verdict precedence

flowchart TD
    S[skill: tree_hash, name, source, has_scripts] --> ADV{active blocking<br/>advisory match?}
    ADV -->|critical/high or hash match| BLOCK[BLOCKED<br/>never attach]
    ADV -->|no| VAL{validation<br/>for this hash?}
    VAL -->|no| UNV[UNVERIFIED<br/>requires_review]
    VAL -->|yes| LVL[level = strongest record]
    LVL --> REV{low/medium advisory<br/>OR has_scripts?}
    REV -->|yes| RR[requires_review]
    REV -->|no| ATT[attachable]

Key design decisions

• Hash = bytes, parse = meaning. content_hash (one document) and hash_skill_tree (whole folder, length-prefixed injective manifest) are byte-exact. Trust binds to the tree hash; any byte change voids a validation and a post-approval tamper is detected. See trust model.
• Progressive disclosure. discover() reads only frontmatter; load()/read_skill_resource fetch bodies and resources on demand with size bounds.
• Grant is the only tool authority. effective_tools narrows below the operator grant, never widens; absence of allowed-tools implies nothing.
• Fail closed. Unknown, script-bearing, or low/medium-advisory skills require review; only a validated, clean skill is attachable.
• Passive by design. No execution, no scheduling, no runtime caps — keeping the framework's agency in the hosts, not the contract library.

Registries (data, not code)

• registry/skills/<name>/ — the vendored curated shelf (byte-verbatim; first-party + catalog-vendored).
• registry/catalog.yaml — the curated vendoring catalog: reviewed entries pinned to upstream commits + whole-tree hashes; the ONLY admissible source list for scripts/vendor_skill.py (validated by abstractskill.catalog).
• registry/validations.yaml — trust attestations bound to tree hashes (regenerated by scripts/refresh_shelf.py; catalog-vendored skills derive their policy from the catalog entry).
• registry/advisories.yaml — specific do-not-use skills (four mandated fields; empty at v1 until an audit or feed names a real one).
• registry/guidance.yaml — category-level risk notices (never block a specific skill).