Adding A Skill
Use this for public skill work in this repo. Keep ordinary skill changes in
skills/<skill-name>/; keep repo-only guidance under .agents/skills/.
First Decide The Skill Kind
- Plain public skill: a normal folder under
skills/<name>/ with
SKILL.md. This is the common case. @agent-native/skills discovers these
dynamically from BuilderIO/skills@main, so there is no framework registry to
edit just to make npx @agent-native/skills@latest add --skill <name> work.
- Instruction-style skill: a plain skill that should optionally write an
always-on managed
AGENTS.md / CLAUDE.md line when users pass
--update-instructions. These need one extra framework change; see
"Managed Instruction Blocks" below.
- App-backed / MCP skill: a skill that registers a hosted/local MCP server
or uses framework-owned install behavior. These are not plain public skills;
inspect
../agent-native/framework/packages/core/src/cli/skills.ts and
../agent-native/framework/packages/skills/src/built-in-apps.ts.
- Plan skills:
visual-plan and visual-recap have generated/synced copies
between this repo and ../agent-native/framework. Do not treat them like a
standalone prose folder.
Plain Public Skill Checklist
Create or update skills/<skill-name>/SKILL.md.
Add skills/<skill-name>/README.md when the skill should appear in the
public catalog. This repo intentionally uses READMEs for public skill pages.
If the collection positioning changes, update root README.md,
.codex-plugin/plugin.json, .claude-plugin/plugin.json, and package.json
descriptions.
Keep the skill concise. Put only essential agent instructions in SKILL.md;
avoid extra docs unless they directly support the skill.
Validate with:
python3 /Users/steve/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/<skill-name>
Smoke-test install discovery locally before claiming the CLI path works:
node ../agent-native/framework/packages/skills/dist/cli.js add --copy . --skill <skill-name> --client codex --scope project --dry-run --json
Run npm run check. If it fails on visual-plan / visual-recap sync while
the change is unrelated, report that specifically instead of rewriting those
skills casually.
@agent-native/skills Install Path
For a plain public skill, the install path is dynamic:
../agent-native/framework/packages/skills/src/index.ts sets
DEFAULT_SKILLS_SOURCE = "BuilderIO/skills".
It materializes that repo, reads plugin manifests via resolveSkillsRoot, and
discovers every skills/*/SKILL.md through discoverSkills.
Therefore a new folder under skills/<name>/ is enough for:
npx @agent-native/skills@latest add --skill <name>
No @agent-native/core built-in registry change is needed unless the skill is
app-backed or needs custom install behavior.
Managed Instruction Blocks
If the skill should affect AGENTS.md / CLAUDE.md through
--update-instructions, update the framework wrapper:
Add a concise line in
../agent-native/framework/packages/skills/src/index.ts inside
instructionContentForSkill(skillName).
Add or update tests in
../agent-native/framework/packages/skills/src/index.spec.ts.
Run:
pnpm --filter @agent-native/skills test -- src/index.spec.ts --runInBand
Use this for durable behavior rules like quick-recap, efficient-fable,
stay-within-limits, and likely docs-first behavior such as
read-the-damn-docs.
App-Backed Or MCP Skills
If a skill needs hosted tools, auth, MCP registration, local-files mode, or
special install flags, inspect the framework before editing:
../agent-native/framework/packages/core/src/cli/skills.ts
../agent-native/framework/packages/skills/src/built-in-apps.ts
../agent-native/framework/packages/skills/src/sync-with-core.spec.ts
Keep the core and standalone @agent-native/skills MCP descriptors in sync.
Plan Skill Sync Gotchas
visual-plan and visual-recap are special:
- Framework contains canonical/generated copies and Plan marketplace bundles.
- This repo's
npm run check compares those copies and can fail for drift
unrelated to a new plain skill.
- When intentionally changing Plan skills, use the framework sync paths instead
of hand-editing generated copies. Search the framework for
sync-plan-marketplace, sync-workspace-skills, and skills.sync.spec.ts.
Final Reporting
When finishing a skill change, tell the user:
- Which skill files changed.
- Whether
@agent-native/skills dynamic install discovery is enough.
- Whether a framework managed-instruction change was added or intentionally
left as a follow-up.
- Which validation commands passed or failed, including unrelated Plan sync
failures.
1---2name: adding-a-skill3description: >-4 Use in the BuilderIO/skills repo whenever adding, updating, publishing,5 documenting, validating, or wiring a public skill. Covers the repo-local skill6 files, root catalog docs, plugin metadata, @agent-native/skills dynamic7 install path, optional managed AGENTS/CLAUDE instruction blocks in8 ../agent-native/framework, and generated/synced Plan skill gotchas.9metadata:10 source: https://skillmd.com/skills/builderio/adding-a-skill11---1213# Adding A Skill1415Use this for public skill work in this repo. Keep ordinary skill changes in16`skills/<skill-name>/`; keep repo-only guidance under `.agents/skills/`.1718## First Decide The Skill Kind1920- **Plain public skill:** a normal folder under `skills/<name>/` with21 `SKILL.md`. This is the common case. `@agent-native/skills` discovers these22 dynamically from `BuilderIO/skills@main`, so there is no framework registry to23 edit just to make `npx @agent-native/skills@latest add --skill <name>` work.24- **Instruction-style skill:** a plain skill that should optionally write an25 always-on managed `AGENTS.md` / `CLAUDE.md` line when users pass26 `--update-instructions`. These need one extra framework change; see27 "Managed Instruction Blocks" below.28- **App-backed / MCP skill:** a skill that registers a hosted/local MCP server29 or uses framework-owned install behavior. These are not plain public skills;30 inspect `../agent-native/framework/packages/core/src/cli/skills.ts` and31 `../agent-native/framework/packages/skills/src/built-in-apps.ts`.32- **Plan skills:** `visual-plan` and `visual-recap` have generated/synced copies33 between this repo and `../agent-native/framework`. Do not treat them like a34 standalone prose folder.3536## Plain Public Skill Checklist37381. Create or update `skills/<skill-name>/SKILL.md`.392. Add `skills/<skill-name>/README.md` when the skill should appear in the40 public catalog. This repo intentionally uses READMEs for public skill pages.413. If the collection positioning changes, update root `README.md`,42 `.codex-plugin/plugin.json`, `.claude-plugin/plugin.json`, and `package.json`43 descriptions.444. Keep the skill concise. Put only essential agent instructions in `SKILL.md`;45 avoid extra docs unless they directly support the skill.465. Validate with:4748 ```sh49 python3 /Users/steve/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/<skill-name>50 ```51526. Smoke-test install discovery locally before claiming the CLI path works:5354 ```sh55 node ../agent-native/framework/packages/skills/dist/cli.js add --copy . --skill <skill-name> --client codex --scope project --dry-run --json56 ```57587. Run `npm run check`. If it fails on `visual-plan` / `visual-recap` sync while59 the change is unrelated, report that specifically instead of rewriting those60 skills casually.6162## @agent-native/skills Install Path6364For a plain public skill, the install path is dynamic:6566- `../agent-native/framework/packages/skills/src/index.ts` sets67 `DEFAULT_SKILLS_SOURCE = "BuilderIO/skills"`.68- It materializes that repo, reads plugin manifests via `resolveSkillsRoot`, and69 discovers every `skills/*/SKILL.md` through `discoverSkills`.70- Therefore a new folder under `skills/<name>/` is enough for:7172 ```sh73 npx @agent-native/skills@latest add --skill <name>74 ```7576No `@agent-native/core` built-in registry change is needed unless the skill is77app-backed or needs custom install behavior.7879## Managed Instruction Blocks8081If the skill should affect `AGENTS.md` / `CLAUDE.md` through82`--update-instructions`, update the framework wrapper:8384- Add a concise line in85 `../agent-native/framework/packages/skills/src/index.ts` inside86 `instructionContentForSkill(skillName)`.87- Add or update tests in88 `../agent-native/framework/packages/skills/src/index.spec.ts`.89- Run:9091 ```sh92 pnpm --filter @agent-native/skills test -- src/index.spec.ts --runInBand93 ```9495Use this for durable behavior rules like `quick-recap`, `efficient-fable`,96`stay-within-limits`, and likely docs-first behavior such as97`read-the-damn-docs`.9899## App-Backed Or MCP Skills100101If a skill needs hosted tools, auth, MCP registration, local-files mode, or102special install flags, inspect the framework before editing:103104- `../agent-native/framework/packages/core/src/cli/skills.ts`105- `../agent-native/framework/packages/skills/src/built-in-apps.ts`106- `../agent-native/framework/packages/skills/src/sync-with-core.spec.ts`107108Keep the core and standalone `@agent-native/skills` MCP descriptors in sync.109110## Plan Skill Sync Gotchas111112`visual-plan` and `visual-recap` are special:113114- Framework contains canonical/generated copies and Plan marketplace bundles.115- This repo's `npm run check` compares those copies and can fail for drift116 unrelated to a new plain skill.117- When intentionally changing Plan skills, use the framework sync paths instead118 of hand-editing generated copies. Search the framework for119 `sync-plan-marketplace`, `sync-workspace-skills`, and `skills.sync.spec.ts`.120121## Final Reporting122123When finishing a skill change, tell the user:124125- Which skill files changed.126- Whether `@agent-native/skills` dynamic install discovery is enough.127- Whether a framework managed-instruction change was added or intentionally128 left as a follow-up.129- Which validation commands passed or failed, including unrelated Plan sync130 failures.