AunoSkills

AunoSkills is a CLI-first package manager, authoring toolkit, and trust layer for SKILL.md-based AI coding skills.

It can inspect a project and recommend skills, resolve and materialize them reproducibly, verify registry provenance and artifact integrity, and now take a skill author through a deterministic init → validate → inspect → pack → verify → publish workflow.

npx aunoskills

AunoSkills is designed around three principles:

Current release: v0.4.0 — skill authoring, deterministic .aunoskill artifacts, independent verification, publication submissions, and the existing secure registry/release trust pipeline.

npx aunoskills

With no subcommand, AunoSkills behaves like init:

scan project
    ↓
build evidence graph
    ↓
recommend relevant skills
    ↓
resolve versions + trust policy
    ↓
verify registry / bundle integrity
    ↓
write manifest + lockfile
    ↓
materialize skills for selected agents

Inspect before changing anything:

npx aunoskills detect
npx aunoskills recommend
npx aunoskills explain typescript-quality

Install reproducibly:

npx aunoskills install
npx aunoskills install --frozen-lockfile
npx aunoskills restore --offline

--yes can skip ordinary confirmation. It does not bypass trust, signature, integrity, path-safety, or capability policy.

Reusable AI-agent instructions are becoming common, but discovery, authoring, trust, versioning, portability, updates, rollback, and CI reproducibility are still fragmented.

AunoSkills puts those concerns behind deterministic contracts.

AunoSkills v0.4 adds a first-class author workflow without creating a hosted marketplace or weakening the registry trust boundary.

skill source
    ↓
init
    ↓
validate
    ↓
inspect
    ↓
pack
    ↓
verify
    ↓
publish submission / workspace
    ↓
registry review + signing

npx aunoskills skill init acme/security-review

The default source remains standard-first:

security-review/
├── SKILL.md
└── auno.json

SKILL.md is the agent-facing source of truth. auno.json carries package-manager metadata such as package identity, version, publisher, compatibility, capabilities, and skill dependencies.

For v0.4, auno.json.id is the package ID and the runtime name is derived from its final path segment:

acme/security-review
     └──────┬──────┘
        runtimeName

npx aunoskills skill validate ./security-review
npx aunoskills skill inspect ./security-review
npx aunoskills skill inspect ./security-review --json

Validation covers metadata, portable identity, semver, source paths, secret-like files, symlinks, dependencies, compatibility, capability declarations, and security findings.

Capability inference is intentionally explainable and conservative. It can flag evidence such as network URLs, shell/process instructions, environment-variable reads, Git mutation, filesystem writes, and possible secret access. Inference is a review signal — never permission to execute.

npx aunoskills skill pack ./security-review --output ./dist/security-review.aunoskill

.aunoskill v1 is a canonical JSON distribution container with exact file bytes encoded as base64.

Its artifact identity excludes volatile host metadata:

normalized POSIX paths
+ lexical file ordering
+ exact file bytes
+ per-file SHA-256
+ canonical metadata
- timestamps
- uid / gid
- host absolute paths
- platform path separators
= deterministic artifact SHA-256

The repository locks one normalized fixture to the same golden artifact digest across Ubuntu, macOS, and Windows.

npx aunoskills skill verify ./dist/security-review.aunoskill
npx aunoskills skill verify ./dist/security-review.aunoskill --json

Verification treats the artifact as untrusted input and independently checks container schema, paths, duplicate/case-colliding entries, canonical base64, file sizes/hashes, manifest correspondence, embedded auno.json, SKILL.md, dependencies, and capabilities.

Important: artifactValid: true does not mean registry verified. Artifact validity and registry trust are separate security properties.

Create a deterministic registry submission:

npx aunoskills skill publish ./security-review --output submission.json

Or publish into an explicitly writable local registry workspace:

npx aunoskills skill publish ./security-review \
  --registry-workspace ../registry-workspace

Publication is immutable by version: identical existing bytes are idempotent; different bytes at the same package/version are rejected.

Authoring does not mint official registry signatures, store private signing keys, or assign verified trust. The registry still performs independent review, validation, signing, and publication.

See packages/authoring/README.md for the package boundary and artifact format.

AunoSkills separates project intelligence from package resolution and filesystem mutation.

Project Scanner
      │
      ▼
Evidence Graph
      │
      ▼
Recommendation Engine
      │
      ▼
Policy-aware Resolver
      │
      ▼
Registry / Trust / Integrity
      │
      ▼
Content-addressed Store
      │
      ▼
Agent Adapter Planner
      │
      ▼
Transactional Materialization

A normal project uses two committed contracts:

aunoskills.json    # human-authored project intent
skills-lock.json   # exact resolved, reproducible state

Machine-local state remains separate:

.aunoskills/state/                 # transactions / ownership / diagnostics
~/.aunoskills/cache/               # content-addressed bundles
~/.aunoskills/registries/<name>/   # verified registry metadata cache

AunoSkills v0.4 targets six coding-agent ecosystems.

Portable skills are shared where agent conventions overlap. Native fan-out is used only when an extension actually requires it.

AunoSkills separates relevance, author claims, artifact validity, registry trust, authenticity, integrity, and requested capability.

Authoring operations never execute skill code. Publishable inventories reject symlinks and block common credential-like files such as .env, private-key files, SSH keys, credential JSON, and service-account files.

.aunoignore can exclude additional content, but cannot re-include security-blocked paths.

A skill cannot become verified by putting that word in auno.json, a .aunoskill artifact, or a publication submission.

configured / pinned trust anchor
            ↓
      signed trust.json
            ↓
       signed index.json
            ↓
manifest SHA-256 + Ed25519 signature
            ↓
       bundle SHA-256

A registry cannot bootstrap its own trust with an unknown self-signed key. Rotations and revocations require authorization from an already trusted active key.

npx aunoskills doctor --check
npx aunoskills audit --registry
npx aunoskills audit --fail-on high

A revoked signer is a CRITICAL finding.

For the complete security model and disclosure guidance, see SECURITY.md.

Long-lived root authority is separated from routine release signing:

offline root private key
        ↓ signs trust.json
pinned root public key
        ↓ delegates
release public key(s)
        ↓ sign index + manifests
registry v2

Release tooling is explicitly staged:

npm run registry:unsigned
npm run registry:sign
npm run registry:verify
npm pack

The protected GitHub release workflow uses a release environment and verifies public output before packaging.

Official registry status: the bundled auno starter registry remains legacy-awaiting-production-trust until authentic production public root/trust material is externally provisioned. No fixture private key or fake production root is committed.

npx aunoskills registry add company https://registry.example.com
npx aunoskills registry add company https://registry.example.com \
  --auth-env AUNOSKILLS_COMPANY_TOKEN
npx aunoskills registry trust company root-2026 BASE64_SPKI_PUBLIC_KEY
npx aunoskills registry refresh company

Only the credential environment-variable name is stored; token values are read at request time and are not persisted in project/lock/user registry config.

npx aunoskills detect
npx aunoskills recommend
npx aunoskills explain <skill>
npx aunoskills add <skill>
npx aunoskills install
npx aunoskills update
npx aunoskills restore
npx aunoskills rollback

npx aunoskills skill init <publisher>/<skill>
npx aunoskills skill validate <dir>
npx aunoskills skill inspect <dir>
npx aunoskills skill pack <dir>
npx aunoskills skill verify <artifact>
npx aunoskills skill publish <dir>

npx aunoskills list
npx aunoskills outdated
npx aunoskills doctor
npx aunoskills audit
npx aunoskills registry list
npx aunoskills cache status
npx aunoskills config list

Machine-readable JSON output is available across the command surface through the existing versioned envelope.

The AunoSkills repository itself dogfoods its manifest/lockfile and verifies the full project on:

Release gates include:

format
→ typecheck
→ compiled build
→ unit/contract tests
→ authoring tests
→ security fixtures
→ E2E lifecycle
→ cross-platform authoring determinism
→ deterministic registry rebuild
→ registry diff gate

AunoSkills keeps authoring, installation, trust, and agent rendering behind focused boundaries.

                         ┌──────────────────────┐
                         │      apps/cli        │
                         └──────────┬───────────┘
                                    │
                 ┌──────────────────┴──────────────────┐
                 │                                     │
                 ▼                                     ▼
       packages/authoring                       packages/core
   init/validate/inspect                   detect/recommend/resolve
     pack/verify/publish                     transact/materialize
                 │                                     │
                 └──────────────┬──────────────────────┘
                                ▼
                 schema / security / registry
                      store / adapters / shared

Boundary rules:

• CLI parses arguments and renders structured results; authoring business logic lives in packages/authoring.
• Scanner knows projects, not skill packages.
• Recommender consumes evidence, not the filesystem directly.
• Resolver behavior is deterministic.
• Registry trust/signing remains outside authoring.
• CAS objects are immutable.
• Adapters plan materialization; Core owns filesystem mutation.
• Failed verification never mutates the project.

Design documents:

• AunoSkills v1 design
• Registry security design
• Secure publishing design
• Skill authoring design

Requirements:

• Node.js >=22
• npm 10.x or compatible behavior
• Windows, macOS, or Linux

npm install --ignore-scripts
npm run verify

Individual gates:

npm run format:check
npm run typecheck
npm run build
npm test
npm run test:security
npm run test:e2e
npm run benchmark

Rebuild the compatibility registry deterministically:

npm run registry:build

Contributions are welcome across authoring, the CLI, project detection, recommendation, agent adapters, security tooling, registry infrastructure, tests, documentation, and starter skills.

Before opening a pull request:

npm install --ignore-scripts
npm run verify
npm run registry:build
git diff --exit-code -- registry/index.json registry/blobs

Read CONTRIBUTING.md for repository workflow. Report sensitive security issues through the process in SECURITY.md.

• Explainable project detection and skill recommendations
• Deterministic version resolution and lockfiles
• Six-agent materialization
• Transactional install/update/remove/restore/rollback
• Content-addressed caching, doctor, and audit
• Ed25519 verified-registry v2 support with rotation/revocation primitives
• Root/release secure publishing infrastructure
• Portable skill initialization, validation, and inspection
• Deterministic .aunoskill packing and independent artifact verification
• Immutable publication submissions/local registry workspaces
• Cross-platform CI and golden authoring artifact determinism

• AunoSkills Cloud
• Hosted marketplace or private-registry service
• Publisher/team dashboard
• SSO / enterprise RBAC / billing
• Transparency log
• Private signing-key manager
• Kernel-level sandboxing
• Fake or fixture production official-registry trust material

See CHANGELOG.md for release history.

AunoSkills CLI/core, authoring toolkit, schemas, adapters, registry tooling, and bundled original starter skills are licensed under Apache-2.0.

AunoSkills is a clean-room implementation. The source code, schemas, registry/artifact formats, security model, CLI architecture, starter skills, documentation, and branding are written independently; third-party non-compatible source/assets are not incorporated into the repository.