@octocodeai/octocode-core

Compressed, versioned bundles of Octocode's MCP tool specs, CLI command specs, Zod query schemas, and Agent Skills — shipped as a zero-dependency npm package.

All content is brotli-compressed at build time and decompressed on demand. No raw source files are published; imports are self-contained.

Installation

npm install @octocodeai/octocode-core
# peer dep for schemas entry point only
npm install zod@>=4

Entry Points

| Import path | What you get | |---|---| | @octocodeai/octocode-core/skills | Agent skill bundles (SKILL.md + all files, brotli-compressed) | | @octocodeai/octocode-core/mcp | MCP tool specs, system prompt, tool names, base schema | | @octocodeai/octocode-core/cli | Smart CLI command specs | | @octocodeai/octocode-core/schemas | Ready-made Zod v4 query schemas for every tool | | @octocodeai/octocode-core/types | TypeScript type definitions only |

/skills — Agent Skill Bundles

Each SkillBundle is a fully self-contained snapshot of one agent skill: the SKILL.md instruction file, README, THINKING notes, and every reference document — ready to install into any agent harness without a network call.

API

import {
  SKILLS,          // readonly SkillBundle[]  — all bundled skills
  skills,          // Record<string, SkillBundle>  — keyed by name
  findSkill,       // (name: string) => SkillBundle | undefined
  listSkillNames,  // () => readonly string[]
  getSkillContent, // (name: string) => string | undefined  — SKILL.md text
} from "@octocodeai/octocode-core/skills";

import type { SkillBundle, SkillFile } from "@octocodeai/octocode-core/skills";

Types

interface SkillFile {
  /** Relative path within the skill folder, e.g. "SKILL.md" or "references/ast-reference.md" */
  path: string;
  /** Raw UTF-8 markdown content. */
  content: string;
}

interface SkillBundle {
  /** Canonical skill identifier / folder name, e.g. "octocode-whitehat". */
  name: string;
  /** Description extracted from the SKILL.md YAML front-matter. */
  description: string;
  /** Full content of SKILL.md — the primary agent instruction. */
  skill: string;
  /** README.md content when present. */
  readme?: string;
  /** THINKING.md content when present. */
  thinking?: string;
  /**
   * Every file in the skill folder — SKILL.md, README.md, THINKING.md,
   * and all files under references/ — ready for verbatim write-out at install time.
   */
  files: readonly SkillFile[];
}

Bundled Skills

| Skill | Description | |---|---| | octocode-whitehat | White-hat security auditor: malware detection, supply-chain attacks, package safety, secrets exposure, CI/CD security, MCP server inspection, bug bounty research across JS/TS/Python/Go/Rust/Ruby |

Installing a Skill

Option A — Octocode CLI (recommended)

The fastest path. One command fetches the skill and installs it for your agent platform:

# Install for all common agent platforms (~/.agents/skills/)
npx octocode skill --name octocode-whitehat

# Install for Pi only
npx octocode skill --name octocode-whitehat --platform pi

# Install for Claude Code + Claude Desktop
npx octocode skill --name octocode-whitehat --platform claude

# Install everywhere at once (symlink mode keeps all in sync on update)
npx octocode skill --name octocode-whitehat --platform all --mode hybrid

# Preview what would be installed without writing anything
npx octocode skill --name octocode-whitehat --platform all --dry-run

Platform paths:

• common → ~/.agents/skills/<name>/
• pi → ~/.pi/agent/skills/<name>/
• cursor → ~/.cursor/skills/<name>/
• claude → Claude Code + Claude Desktop skill folders
• codex → ~/.codex/skills/<name>/

Option B — Programmatic Install (Node.js)

Use the bundle to write skill files to disk yourself — useful in agent harness build scripts, CI, or custom installers:

import { findSkill } from "@octocodeai/octocode-core/skills";
import { writeFileSync, mkdirSync } from "node:fs";
import { dirname, join } from "node:path";
import { homedir } from "node:os";

function installSkill(name: string, targetRoot: string): void {
  const bundle = findSkill(name);
  if (!bundle) throw new Error(`Skill not found: ${name}`);

  for (const file of bundle.files) {
    const dest = join(targetRoot, bundle.name, file.path);
    mkdirSync(dirname(dest), { recursive: true });
    writeFileSync(dest, file.content, "utf8");
  }

  console.log(`✓ installed ${bundle.name} — ${bundle.files.length} files → ${targetRoot}`);
}

// Install octocode-whitehat to the common agent skills directory
installSkill("octocode-whitehat", join(homedir(), ".agents", "skills"));

Option C — Build-Time Extraction (Agent Harness Authors)

Extract core skills into your harness's dist during the build step, so they ship with your package and need no network call at runtime:

// scripts/bundle-core-skills.mjs  (run as part of your build pipeline)
import { SKILLS } from "@octocodeai/octocode-core/skills";
import { writeFileSync, mkdirSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";

const distSkillsDir = resolve(
  dirname(fileURLToPath(import.meta.url)),
  "../dist/skills"
);

for (const bundle of SKILLS) {
  for (const file of bundle.files) {
    const dest = join(distSkillsDir, bundle.name, file.path);
    mkdirSync(dirname(dest), { recursive: true });
    writeFileSync(dest, file.content, "utf8");
  }
  console.log(`  ✓ ${bundle.name} — ${bundle.files.length} files`);
}

console.log(`\nBundled ${SKILLS.length} core skill(s) → ${distSkillsDir}`);

Add to your build pipeline (runs after your own skill copy):

{
  "scripts": {
    "build": "node scripts/copy-skills.mjs && node scripts/bundle-core-skills.mjs && tsc"
  }
}

This is exactly how @octocodeai/pi-extension ships the whitehat skill: no GitHub fetch at runtime, always in sync with the published package version.

Option D — Runtime Read-Prompt-Inject

Inject the SKILL.md directly into an agent's system prompt for zero-install usage. Useful for one-shot activations or testing:

import { getSkillContent } from "@octocodeai/octocode-core/skills";

const whitehatInstructions = getSkillContent("octocode-whitehat");

// In your MCP host / agent harness:
const systemPrompt = `${existingPrompt}\n\n${whitehatInstructions}`;

Note: This activates the skill for the current session only. For persistent activation, use one of the file-install options above so the agent's skill-loader picks it up on every session start.

Discover Available Skills

import { listSkillNames, SKILLS } from "@octocodeai/octocode-core/skills";

// Names only
console.log(listSkillNames());
// => ["octocode-whitehat"]

// Full manifest
for (const bundle of SKILLS) {
  console.log(`${bundle.name} — ${bundle.files.length} files`);
  console.log(`  ${bundle.description.slice(0, 80)}...`);
}

Other Entry Points

/mcp — MCP Tool Specs

import {
  SYSTEM_PROMPT,    // string  — shared research system prompt
  toolNames,        // canonical, stable agent-facing tool names
  baseSchema,       // shared meta fields on every tool query
  tools,            // Record<string, ToolSpec>  — keyed by tool name
  TOOL_SPECS,       // readonly ToolSpec[]  — in canonical agent-facing order
  completeMetadata, // normalized metadata for MCP host registries
  findToolSpec,     // (name: string) => ToolSpec | undefined
} from "@octocodeai/octocode-core/mcp";

/cli — CLI Command Specs

import {
  SYSTEM_PROMPT,   // string
  COMMAND_SPECS,   // readonly CLICommandSpec[]
  commands,        // Record<string, CLICommandSpec>  — keyed by command name
  findCommandSpec, // (name: string) => CLICommandSpec | undefined
} from "@octocodeai/octocode-core/cli";

/schemas — Zod v4 Query Schemas

Ready-made Zod v4 schemas for every Octocode tool — bounds, defaults, enums, and cross-field refinements baked in. Requires zod >= 4 (peer dep).

import {
  toolSchemas,                   // { ghSearchCode, ghGetFileContent, ... }
  findToolSchema,                // (name: string) => ZodTypeAny | undefined
  GitHubCodeSearchQuerySchema,   // individual schema
  baseSchema,
  type GitHubCodeSearchQuery,    // inferred TypeScript type
} from "@octocodeai/octocode-core/schemas";

const query = toolSchemas.ghSearchCode.parse({
  keywords: ["useState"],
});
// => { match: "file", limit: 30, page: 1, keywords: ["useState"] }

Resources

| Resource | Link | |---|---| | Octocode MCP | octocode.ai | | GitHub | bgauryy/octocode-mcp | | Issues | github.com/bgauryy/octocode-mcp/issues |

License

MIT