How to add a new skill, update a shared rule, or change the 4-file spec structure in the Aide repo itself, and how install.sh/uninstall.sh must stay mirrored. Use when: adding or editing a skill or rule under core/, changing spec-structure.md, or touching install.sh/uninstall.sh. Do NOT use for: ordinary spec work (create/analyze/implement/archive) in any project Aide is installed into — this is about maintaining Aide's own source.
Installs into .claude/skills of the current project.
Sponsors
SSkills DirectorySkills Directory
Know which skills are safe — weekly.
SSkills DirectorySkills Directory
Is that skill safe to install?
Are you the author of Aide Repo Maintenance?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/ragnarwestad-aide-repo-maintenance)
---
name: aide-repo-maintenance
description: >-
How to add a new skill, update a shared rule, or change the 4-file spec
structure in the Aide repo itself, and how install.sh/uninstall.sh must
stay mirrored. Use when: adding or editing a skill or rule under core/,
changing spec-structure.md, or touching install.sh/uninstall.sh.
Do NOT use for: ordinary spec work (create/analyze/implement/archive) in
any project Aide is installed into — this is about maintaining Aide's
own source.
disable-model-invocation: true
---
# Adding new functionality to Aide
This only matters when actually adding a skill, changing a rule, or
changing the spec structure — not for ordinary spec work in this repo.
## New skill
1. Read `docs/SKILL_GUIDE.md` for structure and best practices
2. Create `core/skills/<name>/SKILL.md` with frontmatter and core instructions
3. Put heavy documentation in `core/skills/<name>/references/`
4. Run `cd core/implementations/claude-code && ./install.sh`; the manifest records it for uninstall
## Updating rules
1. Edit in `core/rules/` (shared source for all AI tools)
2. Run `core/scripts/build-agents-md.sh` (regenerates `core/AGENTS.md`
AND `core/skills/spec-structure/SKILL.md`)
3. Run `core/implementations/claude-code/install.sh` (rules → `~/.claude/rules/`), `core/implementations/copilot/install.sh` and `core/implementations/codex/install.sh` (new AGENTS.md → `~/.copilot/` and `~/.codex/`)
**`workflows`, `documentation`, `tools-and-scripts` and
`markdown-linting` are skills, not rules,** in `core/skills/`, and `spec-structure` is a rule for Claude Code and a
GENERATED skill for Codex/Copilot. The reason is a byte budget: Codex
appends at most `project_doc_max_bytes` of AGENTS.md — 32768 by default —
and drops the rest silently. `test_core_scripts.py::TestBuildAgentsMd::test_output_fits_codex_read_window`
is what says so now. A new rule in `core/rules/` spends that budget; a
new skill in `core/skills/` does not.
Two consequences worth knowing before editing anything here:
- `core/skills/spec-structure/SKILL.md` is generated. Edit
`core/rules/spec-structure.md` and re-run the build script — never the
skill directly; `test_core_scripts.py::TestSpecStructureSkillIsGenerated`
compares the two bodies byte for byte.
- `core/implementations/claude-code/install.sh` excludes `spec-structure/`
from its skill rsync by name, so it reaches Codex/Copilot only. That
exclusion is why `test_core_skills.py::TestUninstallListsEverySkill`
carries a one-name exception, and it is the third hand-paired list in
this repo after `WORKFLOW_STEPS` and `DEPENDENCY_GATED_STEPS`.
## Changing the spec structure
The 4-file layout is written down in more places than you would guess.
Fixing the templates alone is not enough: the skills decide where an AI
actually writes what, and a skill left behind rebuilds the old layout on
the next run.
1. `core/rules/spec-structure.md` — the rule itself
2. `core/templates/todo/*.template` — what a new spec starts from
3. The create step's `references/file-templates.md`, in the steps
folder beside the runner's own libraries
4. The analyze step's `SKILL.md`, in the same folder, and
`core/skills/task-workflow-assistant/SKILL.md` — the instructions
that decide where an AI actually writes what
5. `core/skills/spec-structure/SKILL.md` — generated from item 1 by
`core/scripts/build-agents-md.sh`; this file is where Codex and Copilot
read the spec layout
6. `core/tests/specs/unit/core/validation/templates/test_templates.py`, which
checks the placeholders the script fills and that a fresh spec claims
no step or phase outcome
No test reads items 1-4 against each other, so a partial change escapes
quietly. Change all six, regenerate, reinstall.
## install.sh and uninstall.sh
These MUST always mirror each other. When changing one, update the other.
Shared scripts (`core/scripts/` → `~/.local/bin/`) are handled by
`core/scripts/_install-bin.sh` — change the script list *there*, not in each installer.
`install-all.sh` / `uninstall-all.sh` (repo root) run all three in sequence.