Consider preserving a custom skills folder for project-specific AI skills

I noticed that a recent ColdBox CLI change consolidated all AI skills into a single .agents/skills/ folder. Previously, the generated structure separated skills into folders like core, custom, and overrides.

I understand the goal of simplifying the structure, and I agree that the separate overrides folder may not be necessary. That concept could probably be handled under custom. However, I think there is still a strong practical reason to keep a clear separation between framework-provided skills and project-authored skills.

The main issue is source control.

The core ColdBox skills feel more like generated framework dependencies. Since they can be regenerated or updated by the CLI, I would generally want to ignore those in .gitignore. But any custom skills I create for my specific application are part of my project and should be committed.

When all skills live directly in .agents/skills/, it becomes much harder to distinguish:

.agents/skills/
    coldbox-core-skill
    another-framework-skill
    my-custom-project-skill
    my-other-custom-skill

Previously, the folder structure made this much easier to manage:

.agents/skills/core/
.agents/skills/custom/
.agents/skills/overrides/

That allowed a .gitignore strategy like this:

# Ignore everything under .agents by default
.agents/**

# Keep the root folder and manifest
!.agents/
!.agents/manifest.json

# Keep project-authored guidelines
!.agents/guidelines/
!.agents/guidelines/custom/
!.agents/guidelines/custom/**
!.agents/guidelines/overrides/
!.agents/guidelines/overrides/**

# Keep project-authored skills
!.agents/skills/
!.agents/skills/custom/
!.agents/skills/custom/**
!.agents/skills/overrides/
!.agents/skills/overrides/**

My suggestion would be to restore a subfolder structure for skills, similar to how .agents/guidelines works. For example:

.agents/skills/core/
.agents/skills/custom/

I do not feel strongly about keeping overrides as a separate folder. I think custom is probably enough. The key point is that project-authored skills should have a predictable location that can be safely committed, while generated ColdBox/framework skills can be ignored.

Would you consider reverting the skills consolidation or updating the manifest structure to support separate skill folders again?

Thanks for all the work on this. I really like the direction of the Agentic ColdBox tooling. I just think this small folder distinction would make the generated structure easier to manage in real-world projects.

Great observation.

This has been a moving target and getting better.
I think we should then definitely create a /.agents/skills-custom for custom skills. And leave the normal skills folder for the automated ones.

However. Make sure the manifest does go into source control.

I am
Also thinking of adding global skills installed at the user home and then symlinked to projects.

Please verify this is on BE now

@lmajano

@lmajano

Ran coldbox ai refresh on existing app:

✅ All missing skills redownloaded
⚠️ Did not create missing skills-custom folder (I wondered if it would)
⚠️ Overwrote my AGENTS.md file, did not respect the , which I had moved down to the bottom of the file. This appears to be a bug. Could not test with fresh install due to error (see below)

Deleted AGENTS.md file + .agents folder and ran coldbox ai install

✅All skills downloaded
✅skills-custom folder appeared
✅AGENTS.md file appeared.

Updated the AGENTS.md file, added a custom skill to skills-custom. Then ran coldbox ai refresh

❓ Manifest File updated with custom skill - unable to test (see below)
❌Lucee error:

ERROR (6.3.2+00857)

The key [MANIFEST] doesn't exist in the arguments scope. The existing keys are [dirName, 2, 3]

C:\Users\Henweigh\.CommandBox\cfml\modules\coldbox-cli\models\SkillManager.cfc: line 500
498:             }
499: 
500:             var alreadyInManifest = !arguments.manifest.customSkills.filter( ( s ) => s.name == dirName ).isEmpty()
501:             if ( alreadyInManifest ) {
502:                return;
called from C:\Users\Henweigh\.CommandBox\cfml\modules\coldbox-cli\models\SkillManager.cfc: line 517
called from C:\Users\Henweigh\.CommandBox\cfml\modules\coldbox-cli\models\AIService.cfc: line 187
called from C:\Users\Henweigh\.CommandBox\cfml\modules\coldbox-cli\commands\coldbox\ai\refresh.cfc: line 21
called from C:\Users\Henweigh\.CommandBox\cfml\system\services\CommandService.cfc: line 443
called from C:\Users\Henweigh\.CommandBox\cfml\system\services\CommandService.cfc: line 225
called from C:\Users\Henweigh\.CommandBox\cfml\system\Shell.cfc: line 865
called from C:\Users\Henweigh\.CommandBox\cfml\system\Shell.cfc: line 680
called from C:\Users\Henweigh\.CommandBox\cfml\system\Bootstrap.cfm: line 165

Can you try on be once it builds, I believe Iaddressed everything

This is complete

Confirmed to be working. Thank you, sir!

Navigation Menu

Repository navigation

Consider preserving a custom skills folder for project-specific AI skills #64

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Consider preserving a custom skills folder for project-specific AI skills #64

Description

Activity

lmajano commented on May 6, 2026

lmajano commented on May 6, 2026

homestar9 commented on May 12, 2026

lmajano commented on May 14, 2026

lmajano commented on May 28, 2026

homestar9 commented on May 28, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions