getcompanion-ai/co-mono
1
0
Fork 0
mirror of https://github.com/getcompanion-ai/co-mono.git synced 2026-04-15 08:03:39 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

feat(coding-agent): add configurable skills directories (#269)

Browse source
This commit is contained in:
Nico Bailon 2025-12-21 11:48:40 -08:00 • committed by GitHub
parent ace3563f0e
commit 70440f7591
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
9 changed files with 186 additions and 39 deletions
Download patch file Download diff file Expand all files Collapse all files

32
packages/coding-agent/docs/skills.md
View file

@ -145,6 +145,36 @@ Skills are discovered from these locations (later wins on name collision):
4. `~/.pi/agent/skills/**/SKILL.md` (Pi user, recursive)
5. `<cwd>/.pi/skills/**/SKILL.md` (Pi project, recursive)
## Configuration
Configure skill loading in `~/.pi/agent/settings.json`:
```json
{
"skills": {
"enabled": true,
"enableCodexUser": true,
"enableClaudeUser": true,
"enableClaudeProject": true,
"enablePiUser": true,
"enablePiProject": true,
"customDirectories": ["~/my-skills-repo"],
"ignoredSkills": ["deprecated-skill"]
}
}
```
| Setting | Default | Description |
|---------|---------|-------------|
| `enabled` | `true` | Master toggle for all skills |
| `enableCodexUser` | `true` | Load from `~/.codex/skills/` |
| `enableClaudeUser` | `true` | Load from `~/.claude/skills/` |
| `enableClaudeProject` | `true` | Load from `<cwd>/.claude/skills/` |
| `enablePiUser` | `true` | Load from `~/.pi/agent/skills/` |
| `enablePiProject` | `true` | Load from `<cwd>/.pi/skills/` |
| `customDirectories` | `[]` | Additional directories to scan (supports `~` expansion) |
| `ignoredSkills` | `[]` | Skill names to exclude |
## How Skills Work
1. At startup, pi scans skill locations and extracts names + descriptions
@ -233,3 +263,5 @@ Settings (`~/.pi/agent/settings.json`):
}
}
```
Use the granular `enable*` flags to disable individual sources (e.g., `enableClaudeUser: false` to skip `~/.claude/skills`).

10
packages/coding-agent/src/core/agent-session.ts
View file

@ -25,7 +25,7 @@ import type { BranchEventResult, HookRunner, TurnEndEvent, TurnStartEvent } from
import type { BashExecutionMessage } from "./messages.js";
import { getApiKeyForModel, getAvailableModels } from "./model-config.js";
import { loadSessionFromEntries, type SessionManager } from "./session-manager.js";
import type { SettingsManager } from "./settings-manager.js";
import type { SettingsManager, SkillsSettings } from "./settings-manager.js";
import { expandSlashCommand, type FileSlashCommand } from "./slash-commands.js";
/** Session-specific events that extend the core AgentEvent */
@ -55,6 +55,7 @@ export interface AgentSessionConfig {
hookRunner?: HookRunner | null;
/** Custom tools for session lifecycle events */
customTools?: LoadedCustomTool[];
skillsSettings?: Required<SkillsSettings>;
}
/** Options for AgentSession.prompt() */
@ -148,6 +149,8 @@ export class AgentSession {
// Custom tools for session lifecycle
private _customTools: LoadedCustomTool[] = [];
private _skillsSettings: Required<SkillsSettings> | undefined;
constructor(config: AgentSessionConfig) {
this.agent = config.agent;
this.sessionManager = config.sessionManager;
@ -156,6 +159,7 @@ export class AgentSession {
this._fileCommands = config.fileCommands ?? [];
this._hookRunner = config.hookRunner ?? null;
this._customTools = config.customTools ?? [];
this._skillsSettings = config.skillsSettings;
}
// =========================================================================
@ -485,6 +489,10 @@ export class AgentSession {
return this._queuedMessages;
}
get skillsSettings(): Required<SkillsSettings> | undefined {
return this._skillsSettings;
}
/**
* Abort current operation and wait for agent to become idle.
*/

20
packages/coding-agent/src/core/settings-manager.ts
View file

@ -16,6 +16,13 @@ export interface RetrySettings {
export interface SkillsSettings {
enabled?: boolean; // default: true
enableCodexUser?: boolean; // default: true
enableClaudeUser?: boolean; // default: true
enableClaudeProject?: boolean; // default: true
enablePiUser?: boolean; // default: true
enablePiProject?: boolean; // default: true
customDirectories?: string[]; // default: []
ignoredSkills?: string[]; // default: []
}
export interface TerminalSettings {
@ -253,6 +260,19 @@ export class SettingsManager {
this.save();
}
getSkillsSettings(): Required<SkillsSettings> {
return {
enabled: this.settings.skills?.enabled ?? true,
enableCodexUser: this.settings.skills?.enableCodexUser ?? true,
enableClaudeUser: this.settings.skills?.enableClaudeUser ?? true,
enableClaudeProject: this.settings.skills?.enableClaudeProject ?? true,
enablePiUser: this.settings.skills?.enablePiUser ?? true,
enablePiProject: this.settings.skills?.enablePiProject ?? true,
customDirectories: this.settings.skills?.customDirectories ?? [],
ignoredSkills: this.settings.skills?.ignoredSkills ?? [],
};
}
getShowImages(): boolean {
return this.settings.terminal?.showImages ?? true;
}

51
packages/coding-agent/src/core/skills.ts
View file

@ -2,6 +2,7 @@ import { existsSync, readdirSync, readFileSync } from "fs";
import { homedir } from "os";
import { basename, dirname, join, resolve } from "path";
import { CONFIG_DIR_NAME } from "../config.js";
import type { SkillsSettings } from "./settings-manager.js";
/**
* Standard frontmatter fields per Agent Skills spec.
@ -315,7 +316,17 @@ function escapeXml(str: string): string {
* Load skills from all configured locations.
* Returns skills and any validation warnings.
*/
export function loadSkills(): LoadSkillsResult {
export function loadSkills(options: SkillsSettings = {}): LoadSkillsResult {
const {
enableCodexUser = true,
enableClaudeUser = true,
enableClaudeProject = true,
enablePiUser = true,
enablePiProject = true,
customDirectories = [],
ignoredSkills = [],
} = options;
const skillMap = new Map<string, Skill>();
const allWarnings: SkillWarning[] = [];
const collisionWarnings: SkillWarning[] = [];
@ -323,6 +334,9 @@ export function loadSkills(): LoadSkillsResult {
function addSkills(result: LoadSkillsResult) {
allWarnings.push(...result.warnings);
for (const skill of result.skills) {
if (ignoredSkills.includes(skill.name)) {
continue;
}
const existing = skillMap.get(skill.name);
if (existing) {
collisionWarnings.push({
@ -335,23 +349,24 @@ export function loadSkills(): LoadSkillsResult {
}
}
// Codex: recursive
const codexUserDir = join(homedir(), ".codex", "skills");
addSkills(loadSkillsFromDirInternal(codexUserDir, "codex-user", "recursive"));
// Claude: single level only
const claudeUserDir = join(homedir(), ".claude", "skills");
addSkills(loadSkillsFromDirInternal(claudeUserDir, "claude-user", "claude"));
const claudeProjectDir = resolve(process.cwd(), ".claude", "skills");
addSkills(loadSkillsFromDirInternal(claudeProjectDir, "claude-project", "claude"));
// Pi: recursive
const globalSkillsDir = join(homedir(), CONFIG_DIR_NAME, "agent", "skills");
addSkills(loadSkillsFromDirInternal(globalSkillsDir, "user", "recursive"));
const projectSkillsDir = resolve(process.cwd(), CONFIG_DIR_NAME, "skills");
addSkills(loadSkillsFromDirInternal(projectSkillsDir, "project", "recursive"));
if (enableCodexUser) {
addSkills(loadSkillsFromDirInternal(join(homedir(), ".codex", "skills"), "codex-user", "recursive"));
}
if (enableClaudeUser) {
addSkills(loadSkillsFromDirInternal(join(homedir(), ".claude", "skills"), "claude-user", "claude"));
}
if (enableClaudeProject) {
addSkills(loadSkillsFromDirInternal(resolve(process.cwd(), ".claude", "skills"), "claude-project", "claude"));
}
if (enablePiUser) {
addSkills(loadSkillsFromDirInternal(join(homedir(), CONFIG_DIR_NAME, "agent", "skills"), "user", "recursive"));
}
if (enablePiProject) {
addSkills(loadSkillsFromDirInternal(resolve(process.cwd(), CONFIG_DIR_NAME, "skills"), "project", "recursive"));
}
for (const customDir of customDirectories) {
addSkills(loadSkillsFromDirInternal(customDir.replace(/^~(?=$|[\\/])/, homedir()), "custom", "recursive"));
}
return {
skills: Array.from(skillMap.values()),

13
packages/coding-agent/src/core/system-prompt.ts
View file

@ -6,6 +6,7 @@ import chalk from "chalk";
import { existsSync, readFileSync } from "fs";
import { join, resolve } from "path";
import { getAgentDir, getDocsPath, getReadmePath } from "../config.js";
import type { SkillsSettings } from "./settings-manager.js";
import { formatSkillsForPrompt, loadSkills } from "./skills.js";
import type { ToolName } from "./tools/index.js";
@ -109,12 +110,12 @@ export interface BuildSystemPromptOptions {
customPrompt?: string;
selectedTools?: ToolName[];
appendSystemPrompt?: string;
skillsEnabled?: boolean;
skillsSettings?: SkillsSettings;
}
/** Build the system prompt with tools, guidelines, and context */
export function buildSystemPrompt(options: BuildSystemPromptOptions = {}): string {
const { customPrompt, selectedTools, appendSystemPrompt, skillsEnabled = true } = options;
const { customPrompt, selectedTools, appendSystemPrompt, skillsSettings } = options;
const resolvedCustomPrompt = resolvePromptInput(customPrompt, "system prompt");
const resolvedAppendPrompt = resolvePromptInput(appendSystemPrompt, "append system prompt");
@ -151,8 +152,8 @@ export function buildSystemPrompt(options: BuildSystemPromptOptions = {}): strin
// Append skills section (only if read tool is available)
const customPromptHasRead = !selectedTools || selectedTools.includes("read");
if (skillsEnabled && customPromptHasRead) {
const { skills } = loadSkills();
if (skillsSettings?.enabled !== false && customPromptHasRead) {
const { skills } = loadSkills(skillsSettings ?? {});
prompt += formatSkillsForPrompt(skills);
}
@ -257,8 +258,8 @@ Documentation:
}
// Append skills section (only if read tool is available)
if (skillsEnabled && hasRead) {
const { skills } = loadSkills();
if (skillsSettings?.enabled !== false && hasRead) {
const { skills } = loadSkills(skillsSettings ?? {});
prompt += formatSkillsForPrompt(skills);
}

1
packages/coding-agent/src/index.ts
View file

@ -104,6 +104,7 @@ export {
type RetrySettings,
type Settings,
SettingsManager,
type SkillsSettings,
} from "./core/settings-manager.js";
// Skills
export {

8
packages/coding-agent/src/main.ts
View file

@ -285,12 +285,15 @@ export async function main(args: string[]) {
}
// Build system prompt
const skillsEnabled = !parsed.noSkills && settingsManager.getSkillsEnabled();
const skillsSettings = settingsManager.getSkillsSettings();
if (parsed.noSkills) {
skillsSettings.enabled = false;
}
const systemPrompt = buildSystemPrompt({
customPrompt: parsed.systemPrompt,
selectedTools: parsed.tools,
appendSystemPrompt: parsed.appendSystemPrompt,
skillsEnabled,
skillsSettings,
});
// Handle session restoration
@ -440,6 +443,7 @@ export async function main(args: string[]) {
fileCommands,
hookRunner,
customTools: loadedCustomTools,
skillsSettings,
});
// Route to appropriate mode

27
packages/coding-agent/src/modes/interactive/interactive-mode.ts
View file

@ -314,18 +314,23 @@ export class InteractiveMode {
}
// Show loaded skills
const { skills, warnings: skillWarnings } = loadSkills();
if (skills.length > 0) {
const skillList = skills.map((s) => theme.fg("dim", ` ${s.filePath}`)).join("\n");
this.chatContainer.addChild(new Text(theme.fg("muted", "Loaded skills:\n") + skillList, 0, 0));
this.chatContainer.addChild(new Spacer(1));
}
const skillsSettings = this.session.skillsSettings;
if (skillsSettings?.enabled !== false) {
const { skills, warnings: skillWarnings } = loadSkills(skillsSettings ?? {});
if (skills.length > 0) {
const skillList = skills.map((s) => theme.fg("dim", ` ${s.filePath}`)).join("\n");
this.chatContainer.addChild(new Text(theme.fg("muted", "Loaded skills:\n") + skillList, 0, 0));
this.chatContainer.addChild(new Spacer(1));
}
// Show skill warnings if any
if (skillWarnings.length > 0) {
const warningList = skillWarnings.map((w) => theme.fg("warning", ` ${w.skillPath}: ${w.message}`)).join("\n");
this.chatContainer.addChild(new Text(theme.fg("warning", "Skill warnings:\n") + warningList, 0, 0));
this.chatContainer.addChild(new Spacer(1));
// Show skill warnings if any
if (skillWarnings.length > 0) {
const warningList = skillWarnings
.map((w) => theme.fg("warning", ` ${w.skillPath}: ${w.message}`))
.join("\n");
this.chatContainer.addChild(new Text(theme.fg("warning", "Skill warnings:\n") + warningList, 0, 0));
this.chatContainer.addChild(new Spacer(1));
}
}
// Show loaded custom tools

63
packages/coding-agent/test/skills.test.ts
View file

@ -1,6 +1,7 @@
import { homedir } from "os";
import { join, resolve } from "path";
import { describe, expect, it } from "vitest";
import { formatSkillsForPrompt, loadSkillsFromDir, type Skill } from "../src/core/skills.js";
import { formatSkillsForPrompt, loadSkills, loadSkillsFromDir, type Skill } from "../src/core/skills.js";
const fixturesDir = resolve(__dirname, "fixtures/skills");
const collisionFixturesDir = resolve(__dirname, "fixtures/skills-collision");
@ -230,6 +231,66 @@ describe("skills", () => {
});
});
describe("loadSkills with options", () => {
it("should load from customDirectories only when built-ins disabled", () => {
const { skills } = loadSkills({
enableCodexUser: false,
enableClaudeUser: false,
enableClaudeProject: false,
enablePiUser: false,
enablePiProject: false,
customDirectories: [fixturesDir],
});
expect(skills.length).toBeGreaterThan(0);
expect(skills.every((s) => s.source === "custom")).toBe(true);
});
it("should filter out ignoredSkills", () => {
const { skills } = loadSkills({
enableCodexUser: false,
enableClaudeUser: false,
enableClaudeProject: false,
enablePiUser: false,
enablePiProject: false,
customDirectories: [join(fixturesDir, "valid-skill")],
ignoredSkills: ["valid-skill"],
});
expect(skills).toHaveLength(0);
});
it("should expand ~ in customDirectories", () => {
const homeSkillsDir = join(homedir(), ".pi/agent/skills");
const { skills: withTilde } = loadSkills({
enableCodexUser: false,
enableClaudeUser: false,
enableClaudeProject: false,
enablePiUser: false,
enablePiProject: false,
customDirectories: ["~/.pi/agent/skills"],
});
const { skills: withoutTilde } = loadSkills({
enableCodexUser: false,
enableClaudeUser: false,
enableClaudeProject: false,
enablePiUser: false,
enablePiProject: false,
customDirectories: [homeSkillsDir],
});
expect(withTilde.length).toBe(withoutTilde.length);
});
it("should return empty when all sources disabled and no custom dirs", () => {
const { skills } = loadSkills({
enableCodexUser: false,
enableClaudeUser: false,
enableClaudeProject: false,
enablePiUser: false,
enablePiProject: false,
});
expect(skills).toHaveLength(0);
});
});
describe("collision handling", () => {
it("should detect name collisions and keep first skill", () => {
// Load from first directory