@q01/claude-skill-core-api

Q01 CoreAPI integration skill for Claude Code.

This package installs a Claude Code skill that guides the implementation of CoreAPI calls in Q01 platform microservices. CoreAPI is the only authorized access layer to metadata-driven tables -- microservices must never access the database directly.

Installation

npx @q01/claude-skill-core-api install

Commands

# Install the skill into Claude Code
npx @q01/claude-skill-core-api install

# Update an existing installation
npx @q01/claude-skill-core-api update

# Remove the skill from Claude Code
npx @q01/claude-skill-core-api uninstall

# Check installation health
npx @q01/claude-skill-core-api doctor

install

Copies all skill files into ~/.claude/skills/q01-core-api/, installs the /core-api command into ~/.claude/commands/q01-core-api/, and appends the skill reference block to ~/.claude/CLAUDE.md (using sentinel comments to track the block). Creates backups of existing files before overwriting.

update

Reinstalls all skill files while preserving the original installedAt timestamp. Updates the CLAUDE.md block if it has changed. Creates a backup of the existing skill directory before updating.

uninstall

Removes all installed skill files, the commands directory, the sentinel block from CLAUDE.md, and the manifest. Leaves the skill directory in place if other files remain.

doctor

Verifies the installation is healthy: checks that all expected files exist, the manifest is consistent, the CLAUDE.md sentinel block is present, and the installed version matches the package version. Exits with code 0 if everything is OK, 1 if problems are found.

Environment Variables

| Variable | Description | |---|---| | Q01_CLAUDE_SKILL_TARGET | Override the default ~/.claude target directory. Useful for testing or custom installations. |

Local Testing

npm test

The test suite uses a temporary directory (via Q01_CLAUDE_SKILL_TARGET) to run install/update/uninstall/doctor cycles without touching your real ~/.claude directory.

Project Structure

bin/
  cli.js                    # CLI entry point

src/
  index.js                  # Programmatic API re-exports
  commands/
    install.js              # Install command
    update.js               # Update command
    uninstall.js            # Uninstall command
    doctor.js               # Doctor (health check) command
  lib/
    logger.js               # Minimal ANSI color logger
    paths.js                # Path resolution (supports Q01_CLAUDE_SKILL_TARGET)
    fs-utils.js             # File system utilities (zero dependencies)
    backup.js               # Backup helpers
    manifest.js             # Manifest read/write

skill/                      # Skill files distributed with the package
  SKILL.md
  CUSTOM_CLAUDE.md
  commands/
    core-api.md
  contract/
    coreapi.rules.md
    coreapi.openapi.yaml
  docs/
    playbook.md
    examples.md
    snippets/
      go_get_list_resty.md
      go_get_single_resty.md
      go_post_bulk_resty.md

test/
  run-tests.js              # Test suite

commands/                   # Source command (not distributed)
  core-api.md

contract/                   # Source contract files (not distributed)
  coreapi.rules.md
  coreapi.openapi.yaml

docs/                       # Source documentation (not distributed)
  playbook.md
  examples.md
  snippets/
    go_get_list_resty.md
    go_get_single_resty.md
    go_post_bulk_resty.md

Usage in Claude Code

After installation, use the /core-api command in Claude Code to start a guided workflow for implementing CoreAPI calls. Claude will ask for the operation type, dimension code, and other required information, then generate the correct code following the skill's rules and canonical snippets.

Esempio di utilizzo:

/plan aggiungi un endpoint /test di tipo GET con relativo controller. Nel controller esegui una chiamata alle core api per la dimensione ORD