bundle-author

---
name: bundle-author
description: This skill should be used when the user asks to "scaffold a new ycc skill",
  "add a skill to the bundle", "extend ycc", "create a new command under ycc", "add
  an agent to ycc", or when the user wants to author new source-of-truth content in
  the ycc/ bundle (skills, commands, agents). Contributor workflow — not a generic
  plugin scaffolder. Respects the source-of-truth / regenerated-bundle split.
---

# ycc Bundle Author

This skill scaffolds new source-of-truth surfaces under `ycc/` — skills, and optionally
matching commands and agents. It is a contributor workflow scoped strictly to this repo's
`ycc/` tree. It writes nothing under `.cursor-plugin/` or `.codex-plugin/` (those are
regenerated), and it emits the exact follow-up commands needed to sync the derived
bundles after scaffolding completes.

## Arguments

Parse `$ARGUMENTS`:

- **skill-name** (required, first positional) — kebab-case identifier, no leading or
  trailing hyphens.
- **--skill-only** — suppress the matching command and stamp `command: false` into
  the skill frontmatter. Use only for passive skills that are never slash-invoked
  (e.g., `karpathy-guidelines` behavioral rules). Without this flag, the scaffolder
  **always** creates the paired command because every normal skill pairs with a
  slash command under the `validate-ycc-commands.sh` policy.
- **--with-agent** — also scaffold `ycc/agents/<skill-name>.md`.
- **--dry-run** — preview only; writes nothing.

The older `--with-command` flag is still accepted (it's now the default) but
prefer omitting it.

## Phase 0: Guards

Before scaffolding, verify all of the following. If any check fails, abort immediately
with a clear, specific message.

1. `skill-name` matches the regex `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`. Reject names with
   uppercase letters, leading/trailing hyphens, or consecutive hyphens.
2. None of the target paths already exist:
   - `ycc/skills/<skill-name>/`
   - Unless `--skill-only`: `ycc/commands/<skill-name>.md`
   - If `--with-agent`: `ycc/agents/<skill-name>.md`
     Use `test -e` for each path and abort if any returns true.
3. Name does not collide with an existing skill, command, or agent. Use `ls` on
   `ycc/skills/`, `ycc/commands/`, and `ycc/agents/` to confirm.
4. Re-read `~/.codex/plugins/ycc/skills/bundle-author/references/when-not-to-scaffold.md`
   and check whether any anti-pattern applies to the user's request. If a match is
   detected, surface it explicitly and ask whether to proceed before continuing.

## Phase 1: Preview

Read `~/.codex/plugins/ycc/skills/bundle-author/references/surface-map.md`. Present the
user with the full list of files that will be created:

- `ycc/skills/<skill-name>/SKILL.md` (with `command: false` stamped in the
  frontmatter when `--skill-only` is set)
- `ycc/skills/<skill-name>/references/` (directory, no files created by default)
- Unless `--skill-only`: `ycc/commands/<skill-name>.md` (default behavior)
- If `--with-agent`: `ycc/agents/<skill-name>.md`

Note that `scripts/` subdirectories are not created by default. If the skill will need
bash helpers, the contributor adds `ycc/skills/<skill-name>/scripts/` manually after
reviewing the scaffolded output.

## Phase 2: Dry-run check

If `--dry-run` was passed: print the file list from Phase 1, then print the exact
post-scaffold commands from Phase 4 (substituting the real skill name), and STOP. Do not
invoke the helper script.

## Phase 3: Scaffold

Invoke the helper:

```
~/.codex/plugins/ycc/skills/bundle-author/scripts/scaffold-skill.sh <skill-name> [--skill-only] [--with-agent]
```

The helper copies templates from
`~/.codex/plugins/ycc/skills/bundle-author/references/templates/` and substitutes
`{{NAME}}` and `{{DESCRIPTION}}` placeholders. If the helper exits with a non-zero
status, STOP and surface its stderr verbatim — do not attempt to repair or work around
the failure.

## Phase 4: Post-scaffold steps

Always emit the following block to the user after a successful scaffold, substituting
`<skill-name>` with the actual name. Omit lines 2 and 3 when the corresponding
flags changed the scaffolded surface.

```
Next steps:
1. Edit ycc/skills/<skill-name>/SKILL.md to replace TODOs.
2. Unless --skill-only: edit ycc/commands/<skill-name>.md to add flag docs,
   usage examples, and any sibling-command cross-references.
3. If --with-agent: edit ycc/agents/<skill-name>.md.
4. If you added scripts under ycc/skills/<skill-name>/scripts/: chmod +x them.
5. Regenerate derived bundles: ./scripts/sync.sh
6. Validate: ./scripts/validate.sh
```

## Important Notes

- Never writes under `.cursor-plugin/` or `.codex-plugin/` — those are regenerated by
  `./scripts/sync.sh` from sources in `ycc/`.
- Never edits `ycc/.codex-plugin/plugin.json` or `.codex-plugin/marketplace.json` —
  those are maintained by the `bundle-release` workflow.
- Refuses generic scaffolding for external repos — see
  `~/.codex/plugins/ycc/skills/bundle-author/references/when-not-to-scaffold.md`.
- Prefer extending an existing skill over adding a near-duplicate. Run `ls ycc/skills/`
  to confirm no existing skill covers the same domain before proceeding.