Skip to content
Skills Library
AI & agents · Building & coding

adding-a-skill

/adding-a-skill

Use in the BuilderIO/skills repo whenever adding, updating, publishing, documenting, validating, or wiring a public skill. Covers the repo-local skill files, root catalog docs, plugin metadata, @agent-native/skills dynamic install path, optional managed AGENTS/CLAUDE instruction blocks in ../agent-native/framework, and generated/synced Plan skill gotchas.

Repository
skills ↗
Licence
MIT
Last repository change
22.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use in the BuilderIO/skills repo whenever adding, updating, publishing, documenting, validating, or wiring a public skill. Covers the repo-local skill files, root catalog docs, plugin metadata, @agent-native/skills dynamic install path, optional managed AGENTS/CLAUDE instruction blocks in ../agent-native/framework, and generated/synced Plan skill gotchas.

Original author description

Use in the BuilderIO/skills repo whenever adding, updating, publishing, documenting, validating, or wiring a public skill. Covers the repo-local skill files, root catalog docs, plugin metadata, @agent-native/skills dynamic install path, optional managed AGENTS/CLAUDE instruction blocks in ../agent-native/framework, and generated/synced Plan skill gotchas.

How it works

  1. First Decide The Skill Kind
  2. Plain Public Skill Checklist
  3. @agent-native/skills Install Path
  4. Managed Instruction Blocks
  5. App-Backed Or MCP Skills
  6. Agent Native Skill Sync Gotchas
  7. Final Reporting
Original SKILL.md headings · 134 lines, 688 words
SKILL.md preview
---
name: adding-a-skill
description: >-
  Use in the BuilderIO/skills repo whenever adding, updating, publishing,
  documenting, validating, or wiring a public skill. Covers the repo-local skill
  files, root catalog docs, plugin metadata, @agent-native/skills dynamic
  install path, optional managed AGENTS/CLAUDE instruction blocks in
  ../agent-native/framework, and generated/synced Plan skill gotchas.
---

# 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.
- **Rewind:** its canonical `SKILL.md` is generated from Agent Native because
  the instructions and local Screen Memory tools share one privacy contract.
  Keep the human README here; use `npm run sync:agent-native-skills` for the
  generated skill instead of editing it by hand.

## Plain Public Skill Checklist

1. Create or update `skills/<skill-name>/SKILL.md`.
2. Add `skills/<skill-name>/README.md` when the skill should appear in the
   public catalog. This repo intentionally uses READMEs for public skill pages.
3. If the collection positioning changes, update root `README.md`,
   `.codex-plugin/plugin.json`, `.claude-plugin/plugin.json`, and `package.json`
   descriptions.
4. Keep the skill concise. Put only essential agent instructions in `SKILL.md`;
   avoid extra docs unless they directly support the skill.
5. Validate with:

   ```sh
   python3 /Users/steve/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/<skill-name>
   ```

6. Smoke-test install discovery locally before claiming the CLI path works:

   ```sh
   node ../agent-native/framework/packages/skills/dist/cli.js add --copy . --skill <skill-name> --client codex --scope project --dry-run --json
   ```

7. 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:

  ```sh
  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:

  ```sh
  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.

## Agent Native Skill Sync Gotchas

`visual-plan`, `visual-recap`, and `rewind` 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`.
- Rewind's `SKILL.md` is generated from
  `packages/core/src/cli/skills-content/rewind-skill.ts`. Its public README is
  preserved as an overlay. The plain-copy installer cannot configure Rewind's
  local MCP connection; public setup docs must use `@agent-native/skills` or
  `@agent-native/core`.
- Plugin manifests that publish the whole `skills/` directory must carry an
  always-on setup directive: invoking Rewind with Clips absent asks permission
  before opening the official install flow, never installs or enables capture
  silently, and keeps Rewind unavailable until Core configures the local MCP
  connection and `screen_memory_status` succeeds.

## 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.
Files in this package (2)
  • SKILL.md 6 KB
  • agents/openai.yaml 1 KB

Versions

The database has no other skills named adding-a-skill.

Database snapshot: 13.11.2026 · package version 4347d05b34af (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100vetskill
    Use when the user is looking for an agent skill, asks "is there a skill for X" or "find a skill that...", wants to compare skills from skills.sh, or asks whether a skill is safe to install.
  • 90skill-repo-curator
    Maintain a public Agent Skills repository. Use when updating skill catalogs, validating SKILL.md files, preparing a release, deprecating skills, reviewing install commands, checking README consistency, or keeping a skills repo ready for npx skills installation.
  • 100repo-skill-maintenance
    Maintain repo-managed agent skills across `.claude/skills` and `.codex/skills`, including targeted sync, validation, index regeneration, drift checks, and Tokki skill visibility. Use when adding or updating a shared skill, migrating a user-managed skill into the repo, or…
  • 95creating-agent-skills
    Create and refine Claude Code Skills. Use when authoring SKILL.md files, building new skills, or improving existing skill structure and best practices.
  • 100skill-writer
    Guide users through creating Agent Skills for Claude Code. Use when the user wants to create, write, author, or design a new Skill, or needs help with SKILL.md files, frontmatter, or skill structure.
  • 90create-skill
    Repo-specific layer for adding a new Claude Code skill to this repository — naming conventions, where the skill lives (distributed, plugin-only, or repo-local), YAML frontmatter pitfalls, and the build/mirror/docs checklist a skill must pass before it ships in the plugin. For…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.