docs(skills): document reduced catalog and budgets
This commit is contained in:
Julian lechner committed
1 parent
831d55b264
commit
260256fe6c
4 files changed
+33
-17
No files matched your search
@@ -96,8 +96,8 @@ Install and update also rebuild internally; the explicit build above lets you ch
|
||||
- Separate install, update, and uninstall scripts: install refuses to run against an already-installed destination,
|
||||
update refuses to run against one that is not installed yet, and uninstall refuses to run against one that was
|
||||
never installed.
|
||||
- User-level plugin installation for Ponytail, i-have-adhd, Superpowers, Context7, Caveman, QMD, Humanizer, Impeccable, and
|
||||
Anthropic Frontend Design, with an interactive extension toggle during both install and update. Only extensions
|
||||
- User-level extension installation for Ponytail, i-have-adhd, Superpowers, Context7, Caveman, QMD, MCPorter,
|
||||
Humanizer, Impeccable, and Anthropic Frontend Design, with an interactive extension toggle during both install and update. Only extensions
|
||||
installed and recorded by this setup can be removed through deselection.
|
||||
- Optional local semantic retrieval for both clients using Qwen3-Embedding-0.6B embeddings and Qwen3-Reranker-0.6B
|
||||
reranking, disabled by default and removable through the install/update choice.
|
||||
@@ -111,8 +111,9 @@ Install and update also rebuild internally; the explicit build above lets you ch
|
||||
- Python `venv` and `pip` when the optional semantic retrieval layer is enabled.
|
||||
- Node.js 22 or newer and `npm` when QMD or MCPorter is selected.
|
||||
|
||||
The Bash scripts do not require PowerShell. The PowerShell scripts remain compatible with PowerShell 5.1;
|
||||
PowerShell 7 can also run them.
|
||||
Core Bash setup scripts do not require PowerShell. The credential commands use Windows Credential Manager and require
|
||||
PowerShell, including when invoked through their Bash wrappers. The PowerShell scripts remain compatible with
|
||||
PowerShell 5.1; PowerShell 7 can also run them.
|
||||
|
||||
## Architecture
|
||||
|
||||
@@ -214,12 +215,18 @@ and replaced, with a warning. Untracked files outside package target paths are l
|
||||
|
||||
Previously managed files no longer shipped are backed up and removed if unchanged. If locally modified, they are
|
||||
backed up and retained with a warning. Backups are stored under `backups/<timestamp>/` in each destination.
|
||||
Local Codex `model`, `model_reasoning_effort`, `plugins`, and `marketplaces` settings are preserved when syncing `config.toml`;
|
||||
other local settings are not generally merged. Dry runs still rebuild `generated/`, but do not modify installation destinations.
|
||||
Codex skill backups use `.agents/.ai-config-skill-backups/` instead, so Codex does not discover backup copies as skills.
|
||||
Existing `.agents/skills/backups/` content is moved there on the next install, update, or uninstall.
|
||||
Codex `config.toml` synchronization merges setup-owned keys while retaining other root keys, extra fields in managed
|
||||
tables, plugin and marketplace tables, and unowned array tables. Other standalone tables may be dropped; the previous
|
||||
file is backed up when content changes. Claude `settings.json` synchronization retains unrelated settings and hooks.
|
||||
Dry runs still rebuild `generated/`, but do not modify installation destinations.
|
||||
|
||||
Selecting Codex also installs shared skills to `.agents/skills`. An interactive extension list includes plugins and
|
||||
Codex skills; unchecked extensions are skipped on installation. Normal install and update ask whether to enable
|
||||
Flashbang, apply the custom status line, and enable Qwen3 semantic retrieval. Choices are saved for Quickupdate.
|
||||
The shared skill catalog includes development skills and focused writing, image, site structure, psychology, and
|
||||
conversion skills. All retained skills are included in both generated clients.
|
||||
The status line defaults to enabled to preserve existing behavior. Disabling it removes the custom client setting and,
|
||||
for Claude, the setup-owned status line script. Disabling retrieval on update removes its setup-owned runtime and index.
|
||||
Dry runs preview changes without updating extensions or retrieval. See [Plugins](docs/plugins.md) for client-specific behavior.
|
||||
@@ -270,7 +277,8 @@ touching anything, unless `-Force`/`--force` is passed; running without a termin
|
||||
fails instead of hanging. Removal reuses the same manifest-sync logic as install and update: every managed file is
|
||||
backed up under `backups/<timestamp>/` before removal, and a file changed locally since the last install/update is
|
||||
backed up but left in place with a warning instead of being deleted. Files this setup never installed are never
|
||||
touched. A destination directory is only deleted once it is fully empty; backups already on disk are always kept.
|
||||
touched. Codex skill backups are kept under `.agents/.ai-config-skill-backups/`. A destination directory is only
|
||||
deleted once it is fully empty; backups already on disk are always kept.
|
||||
Extensions and skills recorded in the ledger are removed the same way `update` removes a deselected extension:
|
||||
pre-existing or manually installed ones outside the ledger are left alone, and a skill file modified since it was
|
||||
installed is kept with a warning. An enabled semantic retrieval setup is disabled and its setup-owned runtime and
|
||||
@@ -285,7 +293,10 @@ keep outside this setup's ledger, or files this setup never installed.
|
||||
|
||||
Codex and Claude Code receive the same shared rules, skills, agents, hooks, and status data. Codex loads applicable rules from generated files, while Claude Code exposes technology- and situation-specific rules as generated skills.
|
||||
|
||||
The default configuration keeps writes workspace-scoped and enables automatic review for eligible escalation requests. Both clients include the same logical agent roles and compact status displays. See [Configuration](docs/configuration.md) for settings, permissions, and limitations.
|
||||
Codex defaults to workspace-write sandboxing and automatic review for eligible escalation requests. Claude uses
|
||||
automatic permissions and enables its sandbox where the platform supports it; explicit deny rules still apply where it
|
||||
does not. Both clients include the same logical agent roles and compact status displays. See
|
||||
[Configuration](docs/configuration.md) for settings, permissions, and limitations.
|
||||
|
||||
## Support
|
||||
|
||||
|
||||
@@ -4,16 +4,16 @@
|
||||
"permanent_context_hard_limit_tokens": 15000,
|
||||
"metrics": {
|
||||
"permanent_context_tokens": {
|
||||
"claude": 14521,
|
||||
"codex": 12997
|
||||
"claude": 5451,
|
||||
"codex": 3767
|
||||
},
|
||||
"instruction_tokens": {
|
||||
"claude": 1485,
|
||||
"codex": 1485
|
||||
},
|
||||
"skill_metadata_tokens": {
|
||||
"claude": 12233,
|
||||
"codex": 10784
|
||||
"claude": 3163,
|
||||
"codex": 1554
|
||||
},
|
||||
"auto_loaded_rule_tokens": {
|
||||
"claude": 678,
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
metric client baseline_tokens
|
||||
permanent_context_tokens claude 14521
|
||||
permanent_context_tokens codex 12997
|
||||
permanent_context_tokens claude 5451
|
||||
permanent_context_tokens codex 3767
|
||||
instruction_tokens claude 1485
|
||||
instruction_tokens codex 1485
|
||||
skill_metadata_tokens claude 12233
|
||||
skill_metadata_tokens codex 10784
|
||||
skill_metadata_tokens claude 3163
|
||||
skill_metadata_tokens codex 1554
|
||||
auto_loaded_rule_tokens claude 678
|
||||
auto_loaded_rule_tokens codex 678
|
||||
rule_catalog_tokens claude 28818
|
||||
|
||||
|
+6
-1
@@ -1,6 +1,6 @@
|
||||
# Skills
|
||||
|
||||
Skills are reusable workflows. Rules are persistent constraints and agents are specialized roles. Each skill is a minimal `SKILL.md` with YAML frontmatter and a small initial workflow so both clients can consume it.
|
||||
Skills are reusable workflows. Rules are persistent constraints and agents are specialized roles. Each skill has a readable `SKILL.md` with YAML frontmatter; detailed guidance may live in that file or its `references/` directory.
|
||||
|
||||
The current structure is organized by purpose:
|
||||
|
||||
@@ -11,9 +11,14 @@ The current structure is organized by purpose:
|
||||
- `implementation/`: SQL, unit-test, and integration-test writing
|
||||
- `verification/`: facts, work-item, and regression verification
|
||||
- `git/`: pull request reviews
|
||||
- `content-strategy/`, `copy-editing/`, `copywriting/`: planning, editing, and writing text
|
||||
- `image/`, `site-architecture/`: visuals and website structure
|
||||
- `marketing-psychology/`, `offers/`, `product-marketing/`, `cro/`: audience understanding, value framing, and conversion
|
||||
|
||||
Each skill defines a focused workflow with the investigation, decision points, and output expected for that task. Keep guidance specific to the skill; shared repository constraints belong in the rules.
|
||||
|
||||
The single catalog in `shared/skills/` includes development skills and focused skills for writing, images, content and site structure, positioning, psychology, and conversion. Builds include every retained skill for both clients. Updating a managed installation backs up and removes unchanged setup-owned skills deleted from the catalog; local changes are backed up and retained.
|
||||
|
||||
Claude's generated package additionally has `skills/rules/`: one skill per focused rule file or directory in
|
||||
`shared/rules/`. The rule-to-skill loading conditions live in `shared/global-instructions.md`, so full rule text loads
|
||||
only when Claude invokes a matching skill instead of sitting permanently in context. Codex reads the matching rule
|
||||
|
||||
Reference in new issue
Block a user