Skip to main content
GeneralSteveGJones

kb-layers

Manage the project's layer vocabulary — list allowed layers with file counts, add new layers, or safely remove unused layers. Reads the shelf-index for usage data; writes CLAUDE.md atomically. No agent dispatch.

Stars
38
Source
SteveGJones/ai-first-sdlc-practices
Updated
2026-05-11
Slug
SteveGJones--ai-first-sdlc-practices--kb-layers
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/SteveGJones/ai-first-sdlc-practices/HEAD/plugins/sdlc-knowledge-base/skills/kb-layers/SKILL.md -o .claude/skills/kb-layers.md

Drops the SKILL.md into .claude/skills/kb-layers.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

Manage KB Layer Vocabulary

Lightweight: This skill reads only index metadata and writes CLAUDE.md. Inline execution is acceptable — no agent dispatch needed.

Manage the project's allowed layer vocabulary for the layer: frontmatter field in library files.

Arguments

Form Description
(none) List allowed layers with file counts from shelf-index
--add <layer> Add a layer to the allowed set
--remove <layer> Remove a layer (refused if any file uses it)
--remove <layer> --force Remove a layer bypassing usage check

Preflight

Read CLAUDE.md and locate the [Knowledge Base] section. Extract library_path (default library/) and shelf_index_path (default library/_shelf-index.md).

Steps

1. Resolve configuration

Read CLAUDE.md [Knowledge Base] section to resolve library_path and shelf_index_path.

2. Run kb_layers.py

python3 -c "
import sys, os, importlib.util
PLUGIN_ROOT = os.environ.get('CLAUDE_PLUGIN_ROOT', '')
SCRIPTS = os.path.join(PLUGIN_ROOT, 'scripts')
INIT = os.path.join(SCRIPTS, '__init__.py')
if os.path.isfile(INIT) and 'sdlc_knowledge_base_scripts' not in sys.modules:
    spec = importlib.util.spec_from_file_location(
        'sdlc_knowledge_base_scripts', INIT,
        submodule_search_locations=[SCRIPTS])
    if spec and spec.loader:
        mod = importlib.util.module_from_spec(spec)
        sys.modules['sdlc_knowledge_base_scripts'] = mod
        spec.loader.exec_module(mod)
from sdlc_knowledge_base_scripts.kb_layers import main
args = ['--project-dir', '<project_dir>', '--shelf-index-path', '<shelf_index_path>']
# Append --add <layer>, --remove <layer>, or --force as appropriate
sys.exit(main(args))
"

Replace <project_dir> with the project root and <shelf_index_path> with the resolved path.

3. Report the result

Print the script output. For list mode:

# Project layer set

Mode: defaults

Allowed layers:
  - methodology            (15 files)
  - evidence               (22 files)
  - domain                 ( 7 files)
  - development            ( 3 files)

What this skill does NOT do

  • Does not read library file content (only the shelf-index Layer: entries)
  • Does not rename layer: values in existing library files — do that manually and run kb-rebuild-indexes
  • Does not dispatch any agent

Errors

  • Invalid layer name — must match ^[a-z][a-z0-9-]*$ (lowercase, hyphenated)
  • Layer in use — use --force to remove anyway (leaves dangling references; kb-lint --strict-layer will catch them)
  • Last remaining layer — cannot remove; at least one layer value is required

Examples

/sdlc-knowledge-base:kb-layers
/sdlc-knowledge-base:kb-layers --add regulatory
/sdlc-knowledge-base:kb-layers --remove clinical-evidence
/sdlc-knowledge-base:kb-layers --remove methodology --force