cyber-aced 0.3.0

package/governances/cli-resolution.md

@@ -0,0 +1,102 @@
+# CLI Resolution
+
+Rules for running a command line tool from a skill. Apply when authoring or auditing a skill that shells out to a script or to a released npm binary.
+
+## Classify the call first
+
+| What the skill runs | How it runs |
+| --- | --- |
+| A script the skill ships | `node <skill-dir>/scripts/<file>` |
+| A released npm CLI the skill does not ship | Local-first: `upx --local-only <pkg>@^<major>`, pinned `npx` only for a cold machine |
+| A tool assumed present (`git`, `gh`, `node`) | Bare name; probe once, fail loudly when missing |
+
+Resolve the runner once at the start of the workflow and reuse it for every later call.
+
+## A script the skill ships
+
+The script is part of the skill folder, built into it, and run with plain `node`.
+
+- Invoke it as `node <skill-dir>/scripts/<file>`. Never through `npx`, `tsx`, a package manager exec, or a global install.
+- Use Node built-ins only, or bundle every dependency into the script. The script must run from an unpacked skill folder with no `node_modules`.
+- Never reference a path outside the skill folder — a sibling skill, a plugin `bin/`, or the package root. Standalone and symlinked installs break such paths silently.
+- A git-sourced install has no built `scripts/`. Document the skill's own pinned fallback for that case: `npx -y <package>@^<version> <command>` with the same arguments.
+
+Script placement and bundling are specified in **skill-design**; this document covers only how the script is invoked.
+
+## A released CLI the skill does not ship
+
+### Preferred — installed copies only
+
+```bash
+upx --local-only <pkg>@^<major> <subcommand>
+```
+
+- `upx` matches a semver **range** against copies already installed — `node_modules` from the current directory upward, nearest first, then the global root — and spawns that binary directly.
+- Pin a **major** range, never an exact version and never a dist tag. One installed copy then serves every caller on that major.
+- `--local-only` never falls back to `npx`. It exits **127** when nothing installed satisfies the range. Read 127 as "not installed", not as "the command failed".
+- `upx` is `@repobuddy/upx`. It is not ambient: it exists only after a global install, so probe `command -v upx` before using it.
+
+### Cold machine — pinned npx
+
+```bash
+npx -y <pkg>@<exact-version> <subcommand>
+```
+
+- Exact version only. Never a range, never a dist tag (`@latest`, `@next`).
+- Read the exact version with `npm view <pkg> version` when authoring, then write it into the skill. Do not resolve it at run time.
+- This is a bootstrap path: it costs a registry lookup on every call and requires network. Use it when `upx` is absent or exited 127 and the call must still succeed.
+
+### Pattern
+
+```bash
+# Resolve <pkg> once
+if command -v upx >/dev/null 2>&1 && upx --local-only <pkg>@^<major> --version >/dev/null 2>&1; then
+  CLI="upx --local-only <pkg>@^<major>"
+else
+  CLI="npx -y <pkg>@<exact-version>"
+fi
+$CLI <subcommand>
+```
+
+Replace `<pkg>` with the npm package name, `<major>` with the major the skill was tested against, and `<exact-version>` with a released version of that major.
+
+### An optional lookup never falls back
+
+When the call is a lookup that may legitimately find nothing — a governance override, an optional config — stop at the local tier:
+
+```bash
+upx --local-only <pkg>@^<major> <subcommand> || true
+```
+
+Exit 127, or any other non-zero exit, means "no result". The skill continues with its own default and never reaches for `npx`.
+
+## Error handling
+
+Surface a missing tool; never proceed silently.
+
+```
+Error: <pkg> not available. Install one of:
+  npm install -g <pkg>            # global
+  pnpm add -D <pkg>               # repo-local devDependency
+```
+
+Distinguish the two failures when reporting: exit 127 from `upx --local-only` means nothing installed satisfies the range; a non-zero exit from the CLI itself means the command ran and failed.
+
+## Rules
+
+- Never hardcode `node_modules/.bin/<bin>`. The path is implementation-specific and breaks across workspaces and package managers.
+- Never rely on repo-specific package scripts (`pnpm <bin>`, `npm run <bin>`) — local conventions, not portable.
+- Never pass a range or a dist tag to `npx`; never pass an exact version to `upx --local-only`.
+- Never use `npx` for a call the skill makes repeatedly in one run.
+- A skill's own script never depends on a package runner. The pinned `npx` fallback belongs to the skill, not to the script.
+
+## References
+
+Related governances (load on demand; read stdout as authoritative):
+
+```bash
+governance show skill-design
+governance show agent-tool-output
+```
+
+- <https://github.com/repobuddy/upx> — `upx` resolution order and the `--local-only` flag

package/governances/skill-design.md

@@ -0,0 +1,258 @@
+# Skill Design
+
+Rules for authoring SKILL.md files that agents load on demand. Apply when creating, generalizing, or auditing a skill — before adding scripts or CLI instructions.
+
+## Structure
+
+SKILL.md must be agent-first: dense normative rules the agent executes without opening linked files first.
+
+- Do not include `## Why`, `## Rationale`, `## Background`, or `## Context` sections.
+- Do not include causal explanation ("because…") or rationale prose in the body.
+- One-line scope ("Apply when…") is allowed at the top.
+- Put optional depth in `## References` at the end — `governance show` commands, external HTTPS URLs, sibling files in the same skill folder only.
+
+**SKILL.md structure:**
+
+```markdown
+# Skill Title
+## When to use / Prerequisites   # short scope
+## Workflow                      # numbered steps, decision logic
+## Anti-patterns                 # optional
+## References                    # on-demand standards, external URLs, reference.md — no repo file paths
+```
+
+Do not embed References content or links to sibling files mid-workflow.
+
+## Core principles
+
+### Decisions over documentation
+
+Encode what to decide and how. Do not repeat generic best practices, API docs, or facts the model can derive without the skill.
+
+### Narrow and composable
+
+One workflow per skill. A skill is selected one of three ways — matched against a situation, named by a caller, or fired by an event. Declare that choice in the `description`; never infer it from a visibility flag.
+
+- **Name-only skills** (loaded by name from another skill, never matched to a user situation) set the `description` to exactly `"By name only"` — nothing else. The minimal description is the mechanism, not a label for it: the `description` is the only surface the model matches against, so every word added to it is another handle for a spurious match. Identity — what the skill is, who calls it, what it returns — belongs in the body and README, which the caller reads after loading it by name.
+- **`user-invocable` is a visibility flag only.** It controls whether a skill appears in the user's command list. It never determines how a skill is selected, and must not be read as one: a skill may legitimately be `user-invocable: false` and still situationally triggered.
+- Whether a skill can run standalone is documentation for its README, not a declared kind. A self-contained engine and a fragment of a larger capability are selected the same way and carry the same minimal description.
+- Neither type should be loaded as ambient context.
+
+### No baked-in opinions
+
+Detect the user's setup (package manager, monorepo shape, editor, OS paths) at runtime rather than assuming a specific stack. If the skill only applies to one stack, say so explicitly in the description.
+
+## Placement and scope
+
+Where a skill file lives depends on who consumes it. Whole-repo layout (manifests, CI, archetypes) is covered in **skill-repo-structure** — load from References when scaffolding a library repo.
+
+### Skill placement
+
+Use **placement** for where a skill lives; do not call this axis "type".
+
+| Placement | Location | Use case |
+| --- | --- | --- |
+| **User** | `~/.agents/skills/<name>/` | Personal skills across all projects |
+| **Project private** | `.agents/skills/<name>/` | Contributor tooling scoped to one repo |
+| **Project public** | `skills/<name>/` | Shipped with a package or installed via `npx skills add` |
+
+### Skill patterns
+
+Use **pattern** for the workflow shape; do not overload "kind" or "type" here.
+
+| Pattern | Use case |
+| --- | --- |
+| **Process** | Multi-step workflows where sequence and decision logic matter |
+| **Tool-based** | Workflows centered on consistent use of tools, systems, or connectors |
+| **Standard** | Workflows that enforce tone, structure, formatting, or quality bars |
+| **Persona** | Loads an expert stance, decision style, and working behavior into the session |
+
+Repo-internal skills must include `metadata: internal: true` in frontmatter.
+Persona skills must include `metadata.persona: "true"`.
+
+### Patch and local rules
+
+- Upstream contributions from a local install map to `skills/<name>/…` in the source repo — never `.agents/skills/` upstream.
+- **`SKILL.local.md`** extends a skill locally; never commit or push it upstream.
+- Include every changed file under the skill folder when patching (not only `SKILL.md`).
+
+## Progressive disclosure
+
+Keep SKILL.md concise — essential workflow and decision logic only.
+
+- Put detailed reference material in sibling files (`reference.md`, `examples.md`) in the same skill folder.
+- Link sibling files **only from References**; agent reads them when stuck, not by default.
+- Link references **one level deep** from SKILL.md; avoid chains of nested files.
+- Aim to keep SKILL.md under ~500 lines; split when a skill grows beyond that.
+
+## Extract deterministic logic
+
+When a step produces the same output given the same input and needs no judgment, move it out of prose:
+
+- Prefer an **existing project CLI** or a small **script** in the skill's `scripts/` directory.
+- The skill retains **when** to invoke the tool; the tool retains **how**.
+- Candidates: text manipulation, file I/O, structured data transforms, validation with fixed rules.
+
+Do not re-derive deterministic steps in natural language each run.
+
+### Keep scripts inside the skill folder
+
+The skill folder is the unit an installer copies (`skills add --skill <name>` takes that folder and nothing else).
+
+- Put every script the skill runs in its own `scripts/`, and invoke it as `node <skill-dir>/scripts/<file>`.
+- Never reference a path outside the skill folder: a sibling skill, a plugin's `bin/`, or the package root. Standalone copies and symlinked installs break such paths without an error.
+- Use Node built-ins only, or bundle dependencies into the script. The script itself never depends on `npx`, `tsx`, or a global install; the pinned `npx` fallback below is the skill's, not the script's. For a released CLI the skill depends on but does not ship, follow **cli-resolution**.
+
+### Share logic by bundling it into each skill
+
+When several skills, or a skill and a package CLI, need the same logic:
+
+- Author it once in the package source, typed and tested there.
+- Have the build emit a self-contained bundle into the `scripts/` of each skill that uses it. Start the bundle with a header naming its source file and saying it is generated, then the usage comment an agent reads when stuck. Minify the rest.
+- Do not commit the bundles. Gitignore them, build them in `prepack`, and ship them through the npm package's `files`.
+- Add a CI check that packs the package, unpacks it with no `node_modules`, and runs each bundle from the unpacked skill folder.
+- If the build is cached (for example by Turborepo), list each bundle as a build output by exact path. A glob such as `skills/**` restores cached copies over hand-written scripts.
+- Keep the tests with the source, outside the skill folder, so installs do not copy them.
+- Expose the same commands in the package CLI, and give each such skill a pinned fallback: when `scripts/<file>` is missing or cannot run, call `npx -y <package>@^<version> <command>` with the same arguments. A skill installed from git has no built `scripts/`, and this is how it still works.
+- Distribute the plugin from npm where the harness supports an npm plugin source. Git-sourced installs, including organization-distributed marketplaces that exclude npm sources, use the fallback.
+
+When a skill includes `scripts/` or documents CLI commands agents run, load **agent-tool-output** from References for stdout, JSON, non-interactive, and stderr rules.
+
+## Description and structure
+
+### Frontmatter
+
+- `name` must match the parent directory name exactly.
+- `description` must contain `"Use this skill when"` or `"When to use"` trigger language — **unless the skill is name-only**, whose `description` is exactly `"By name only"` and carries no trigger language at all.
+- Keep `description` ≤120 characters — long descriptions are truncated in the agent context window.
+- `compatibility` — optional; declare environment constraints (required tools, network access, OS, runtime version). Include only when the skill has requirements the agent cannot assume.
+
+#### Runtime fields
+
+Support varies by platform; the notes below are Claude Code's documented behavior. Set none of these unless the skill needs them — each one is a deviation the reader must account for.
+
+| Field | Effect |
+| --- | --- |
+| `allowed-tools` | **Pre-approves** the listed tools for the invoking turn. It does not restrict the tool pool — every other tool stays callable. The grant clears on the user's next message. |
+| `disallowed-tools` | Removes tools from the pool while the skill is active. This is the field that restricts. Also clears on the next message. |
+| `model` | Model to use while the skill is active. Applies for the rest of the current turn only; the session model resumes on the next prompt. |
+| `effort` | Effort level while the skill is active: `low`, `medium`, `high`, `xhigh`, `max`. Same turn-scoped lifetime as `model`. |
+| `context: fork` | Runs the skill in a subagent, with the skill body as the task prompt. Pair with `agent:` to choose the subagent type. Only meaningful for a skill that states a task — a reference or stance skill forked this way receives no actionable prompt and returns nothing useful. |
+| `paths` | Glob patterns limiting automatic activation to matching files. |
+
+A skill cannot express a tool **allowlist** — `allowed-tools` grants and `disallowed-tools` denies, but neither says "only these". A hard allowlist, `permissionMode`, `maxTurns`, persistent `memory`, `mcpServers`, and worktree `isolation` remain agent-definition fields. Reach for an agent definition when one of those is the actual requirement, not for `model` or `effort` alone.
+
+### skill.json — install-time metadata
+
+`skill.json` is an optional sidecar file in the same directory as `SKILL.md`. It holds install-time metadata that the `skills add` / `skills update` installer reads. It is **not** loaded into agent context, so it costs zero tokens at runtime.
+
+Do not put install-time metadata in SKILL.md frontmatter — agents load it unnecessarily.
+
+**Supported fields:**
+
+```json
+{
+  "distribution": {
+    "install_via": "package_manager",
+    "package": {
+      "name": "cyber-asana",
+      "bin": "cyber-asana"
+    }
+  }
+}
+```
+
+**`distribution`** — declare the required install channel.
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `install_via` | yes | `"package_manager"` — must be installed via npm, not source control |
+| `package.name` | when `install_via: package_manager` | npm package that ships the skill binary |
+| `package.bin` | no | binary name; defaults to `package.name` |
+
+Use `install_via: package_manager` when the skill depends on a released binary from the same repo. Source-based `skills add org/repo` will skip such skills and print an `npm install` hint.
+
+### Activation
+
+The `activation` field belongs in **SKILL.md frontmatter** as a **top-level field** (not nested under `metadata:`). Agents need this information to know whether a hook is involved; not all agents support hooks, so it must travel with the skill file.
+
+```yaml
+---
+name: my-skill
+activation: per-situation
+description: "Use this skill when..."
+---
+```
+
+| `activation` | Claude Code | Cursor | Codex |
+| --- | --- | --- | --- |
+| `per-situation` | — | — | — |
+| `session-start` | `SessionStart` | `sessionStart` | `SessionStart` |
+| `session-end` | `SessionEnd` | `sessionEnd` | — |
+| `pre-tool-use` | `PreToolUse` | `preToolUse` | — |
+| `post-tool-use` | `PostToolUse` | `postToolUse` | `PostToolUse` |
+| `post-tool-use-failure` | — | `postToolUseFailure` | — |
+| `before-submit-prompt` | `UserPromptSubmit` | `beforeSubmitPrompt` | — |
+| `before-shell-execution` | — | `beforeShellExecution` | — |
+| `after-shell-execution` | — | `afterShellExecution` | — |
+| `before-mcp-execution` | — | `beforeMCPExecution` | — |
+| `after-mcp-execution` | — | `afterMCPExecution` | — |
+| `before-read-file` | — | `beforeReadFile` | — |
+| `after-file-edit` | — | `afterFileEdit` | — |
+| `subagent-start` | — | `subagentStart` | — |
+| `subagent-stop` | — | `subagentStop` | `SubagentStop` |
+| `pre-compact` | `PreCompact` | `preCompact` | — |
+| `stop` | `Stop` | `stop` | `Stop` |
+| `after-agent-response` | — | `afterAgentResponse` | — |
+| `after-agent-thought` | — | `afterAgentThought` | — |
+| `before-tab-file-read` | — | `beforeTabFileRead` | — |
+| `after-tab-file-edit` | — | `afterTabFileEdit` | — |
+
+— = no documented equivalent on that host.
+
+**Default:** omit or set `per-situation` — no hook; load via `description` or explicit invoke.
+
+**Hook-backed skills:** set `activation` to the normalized event, then register with `hook register --event …` (cyberplace CLI maps `session-start` → `SessionStart` / `sessionStart`, `post-tool-use` → `PostToolUse` / `postToolUse`). CLI today supports `SessionStart` and `PostToolUse` only; other values are portable declarations until hosts implement them.
+
+**Defaults by pattern:** persona → `per-situation` (opt-in via `description`); discipline / always-on injection → `session-start`; process / tool-based / standard → `per-situation` or omit.
+
+Deprecated: `metadata.activation` in SKILL.md frontmatter. Use top-level `activation:` instead.
+
+### Body
+
+- Include actionable steps, numbered instructions, or decision logic — not just a restatement of the description.
+- Do not instruct generic behavior the model already follows ("write clean code", "be helpful").
+
+## Anti-patterns
+
+- Rationale or "because…" prose in the body
+- `## Why`, `## Rationale`, `## Background`, or `## Context` sections
+- Links to other repository files mid-workflow
+- Mid-body links to sibling skill files (use References at end)
+
+## Governance lookup order
+
+A skill that reads a governance at run time stops at the first hit:
+
+1. `.agents/governances/<name>.md` — project override.
+2. Only when an installed copy exists: `upx --local-only buddy-agent-harness@^<major> governance show <name> --overrides-only` when `upx` is on PATH; else `buddy-agent-harness governance show <name> --overrides-only` when `command -v buddy-agent-harness` finds it. Exit 127 from `upx`, or any non-zero exit, means no override. Never through `npx`.
+3. `references/governances/<name>.md` inside the skill — the default copy, committed to git.
+
+Copies live at `<skill>/references/governances/<name>.md`, and the files in that folder declare which governances the skill uses. A skill copies every governance a copied governance references, and lists every copy in its SKILL.md References, so each stays one level deep. A pointer inside a copy (`governance show <other>`) is read as "load `references/governances/<other>.md`".
+
+`buddy-agent-harness governance` and the copy step in `universal-plugin plugin build` are planned (tracked in https://github.com/repobuddy/buddy-agent-harness/issues/122). Until they ship, a skill uses step 3 only.
+
+## References
+
+Related governances (load on demand; read stdout as authoritative):
+
+```bash
+npx cyberplace@<version> governance show skill-repo-structure
+npx cyberplace@<version> governance show agent-tool-output
+npx cyberplace@<version> governance show universal-plugin
+```
+
+Runtime field reference (re-verify before relying on a version-gated field):
+
+- <https://code.claude.com/docs/en/skills> — skill frontmatter, invocation control, `context: fork`
+- <https://code.claude.com/docs/en/sub-agents> — agent-definition frontmatter, `skills:` preloading

package/governances/skill-repo-structure.md

@@ -0,0 +1,173 @@
+# Skill Repo Structure
+
+Rules for organizing a **repository that ships one or more Agent Skills** — directories, manifests, contributor internals, and CI. Apply when creating a skill library, running `init-skill-repo`, or auditing whether a repo is a well-formed skill collection.
+
+This governance covers **repo layout**. Per-skill authoring rules live in **skill-design**; per-skill format baseline is the agentskills.io specification (see References).
+
+## Repo archetypes
+
+Pick the **primary** archetype. Hybrid repos are fine if each layer is intentional.
+
+### Collection
+
+Skills only — publish via `npx skills add owner/repo`.
+
+**Typical layout:**
+
+```text
+LICENSE
+README.md
+skills/
+  <skill-name>/
+    SKILL.md
+    README.md          # human-facing usage + install (skills.sh listing hygiene)
+```
+
+**Optional:** `skills.sh.json`, `.claude-plugin/marketplace.json`, `template/`, `spec/` (pointer to agentskills.io).
+
+### Maintained library
+
+Collection plus validation and install hygiene.
+
+**Add:**
+
+- `AGENTS.md` (and `CLAUDE.md` → symlink when using Claude Code)
+- CI that runs skill validation on PRs touching `skills/`
+- Documented install commands in README
+- Optional committed `skills-lock.json` when the repo dogfoods `npx skills add`
+
+**Validate with:** your skill-validation tool (e.g. the aced `improve-skill` skill's `validate.mts` engine).
+
+### Tooling library
+
+Maintained library plus npm CLI, governances, or hooks shipped from the same repo.
+
+**Add (as needed):**
+
+```text
+governances/           # version-pinned standards (cyberplace pattern)
+src/                   # CLI source
+package.json           # publishable bin
+.changeset/            # if npm releases use Changesets
+```
+
+**Require:** a single documented verify command in AGENTS.md (typecheck + lint + test + audit, or equivalent for the stack).
+
+### Plugin bundle
+
+Skills grouped under named bundles for Claude/plugin marketplaces.
+
+**Layout:**
+
+```text
+plugins/
+  <bundle-name>/
+    skills/
+      <skill-name>/
+        SKILL.md
+    .claude-plugin/
+```
+
+Do not treat plugin-bundle layout as the default — most repos use flat `skills/<name>/`.
+
+## Required for any public skill repo
+
+1. **`LICENSE`** at repo root.
+2. **Public skills under `skills/<name>/SKILL.md`** (or documented bundle path for plugin archetype).
+3. **Each skill complies** with agentskills.io: `name` matches directory; valid frontmatter; optional folders only as `scripts/`, `references/`, `assets/` unless documented otherwise.
+4. **Each public skill includes `README.md`** alongside `SKILL.md` — when to use, what it does, and `npx skills add owner/repo --skill <name>`. Agent instructions stay in `SKILL.md`; README is for humans and skills.sh discovery.
+5. **No loose `SKILL.md`** at repo root or outside a named skill directory.
+6. **Root README** with install instructions (`npx skills add …`) for consumer-facing repos.
+
+## Recommended for maintained and tooling libraries
+
+| Artifact | Purpose |
+| --- | --- |
+| `AGENTS.md` | Agent-facing commands, architecture, pointers to governances |
+| `.agents/skills/` | Repo-internal contributor skills (`metadata: internal: true`) |
+| `skills.sh.json` | skills.sh groupings and install scopes |
+| `.claude-plugin/marketplace.json` | Claude plugin marketplace groupings |
+| CI on `skills/` | Block merges that fail skill validation |
+| `awesome-skills.json` | Curated discovery (cyberplace-specific; optional elsewhere) |
+
+## Contributor and patch conventions
+
+These extend **skill-design** placement rules for library repos:
+
+| Placement | Location | Notes |
+| --- | --- | --- |
+| **User** | `~/.agents/skills/<name>/` | User machine; not in the skill repo |
+| **Project private** | `.agents/skills/<name>/` | `metadata: internal: true`; not shipped in `npx skills add` public tree |
+| **Project public** | `skills/<name>/` | Installed by consumers |
+
+**Upstream patches** from a local install always map to `skills/<name>/…` in the source repo — never `.agents/skills/` in upstream.
+
+## Discipline sections
+
+AGENTS.md **Discipline** sections (for example `## Commit Discipline` injected by SessionStart hooks) are **agent-first**:
+
+- **Dense normative rules** in the section body — unit-of-work definition, staging rules, habits.
+- **Self-contained** — no links to other repository files; agent follows discipline without loading governances first.
+- **`### References` at section bottom** — commit-helper skill name, `governance show` one-liners only.
+- **Do not** paste full governance bodies or ecosystem surveys into AGENTS.md.
+
+Use **`init-commit-discipline`** to inject commit discipline for this profile.
+
+## Optional manifests (do not require all)
+
+| File | When |
+| --- | --- |
+| `skills-lock.json` | Repo records installed skills for reproducibility |
+| `skills.sh.json` | Listing on skills.sh with groupings/scopes |
+| `.claude-plugin/marketplace.json` | Claude plugin UX |
+| `governances/` | Repo ships version-pinned standards loadable via `governance show` |
+
+Prefer **digest + lockfile** over ad hoc path scraping for reproducible installs.
+
+## Anti-patterns
+
+- Duplicating the same skill in `skills/` and `.agents/skills/` without a documented reason
+- Bloating AGENTS.md with full governance bodies — use `governance show` pointers in References instead
+- Embedding reference-repo catalogs or surveys in governances — keep those outside agent-loaded standards
+- Rationale or "because…" prose in governances, discipline sections, or public skills
+- `## Why`, `## Rationale`, `## Background`, or `## Context` sections in agent-loaded artifacts
+- Linking to repository files (ADRs, research, other governances as paths) from governances, discipline sections, or public skills
+- Assuming `node_modules` or install paths for loading governances from other repos
+- Running no CI on skill-only repos that accept external PRs
+- Committing `SKILL.local.md` or secrets into public skill trees
+
+## Detecting a skill repo
+
+Treat a repository as a **skill repo** when any of:
+
+- `skills/**/SKILL.md` exists (or `plugins/**/skills/**/SKILL.md` for bundle archetype)
+- README or package scripts document a skill-validation command
+- Primary purpose is distributing Agent Skills (not an application that happens to have one skill)
+
+Use **`init-skill-repo`** (when shipped) to scaffold and wire disciplines for this profile.
+
+## Verification
+
+| Archetype | Minimum check |
+| --- | --- |
+| Collection | Manual or `skills-ref validate` per skill |
+| Maintained / tooling | your skill-validation tool (e.g. the aced `improve-skill` `validate.mts` engine) in CI |
+| Tooling library | Full repo verify command documented in AGENTS.md |
+
+Full quality review (Q6–Q13, E3–E8): run the **improve-skill** agent skill after mechanical validation passes.
+
+## References
+
+**Related governances** (load on demand):
+
+```bash
+npx cyberplace@<version> governance show skill-design
+```
+
+| Layer | Source |
+| --- | --- |
+| Single skill format | [agentskills.io specification](https://agentskills.io/specification) |
+| Skill content quality | `governance show skill-design` |
+| Skill security | `governance show skill-security` (when shipped) |
+| Org operational governance | [OWASP AST09](https://owasp.org/www-project-agentic-skills-top-10/) — out of scope for repo layout |
+| Distribution RFCs | [agentskills distribution RFCs](https://github.com/agentskills/agentskills/issues/255) — future `.well-known` manifests |

package/package.json

@@ -0,0 +1,44 @@
+{
+	"name": "cyber-aced",
+	"version": "0.3.0",
+	"description": "Agent Config Evaluation & Development. Spec, evaluate, and improve agent configurations: skills, AGENTS.md sections, subagent definitions, and commands.",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/cyberuni/cyber-sdd.git",
+		"directory": "plugins/aced"
+	},
+	"homepage": "https://github.com/cyberuni/cyber-sdd",
+	"license": "MIT",
+	"type": "module",
+	"bin": {
+		"aced-bench": "./dist/aced-bench.js"
+	},
+	"files": [
+		"dist",
+		"skills",
+		"agents",
+		"governances",
+		".plugin",
+		".codex-plugin",
+		".claude-plugin",
+		"!skills/**/*.test.mts"
+	],
+	"dependencies": {
+		"@cyberuni/agent-harness": "0.5.0"
+	},
+	"scripts": {
+		"build": "tsdown",
+		"check:spec": "node ../sdd/skills/check-project-specs/scripts/check-project-specs.mts",
+		"test": "node --test \"skills/*/scripts/*.test.mts\"",
+		"typecheck": "tsc -p tsconfig.json"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"devDependencies": {
+		"tsdown": "^0.23.0"
+	},
+	"engines": {
+		"node": ">=22.11"
+	}
+}