# Adding A Skill

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-builderio-skills-adding-a-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [BuilderIO](https://agentstack.voostack.com/s/builderio)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [BuilderIO](https://github.com/BuilderIO)
- **Source:** https://github.com/BuilderIO/skills/tree/main/.agents/skills/adding-a-skill
- **Website:** https://www.agent-native.com/

## Install

```sh
agentstack add skill-builderio-skills-adding-a-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Adding A Skill

Use this for public skill work in this repo. Keep ordinary skill changes in
`skills//`; keep repo-only guidance under `.agents/skills/`.

## First Decide The Skill Kind

- **Plain public skill:** a normal folder under `skills//` 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 ` 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

1. Create or update `skills//SKILL.md`.
2. Add `skills//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/
   ```

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  --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//` is enough for:

  ```sh
  npx @agent-native/skills@latest add --skill 
  ```

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.

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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [BuilderIO](https://github.com/BuilderIO)
- **Source:** [BuilderIO/skills](https://github.com/BuilderIO/skills)
- **License:** MIT
- **Homepage:** https://www.agent-native.com/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-builderio-skills-adding-a-skill
- Seller: https://agentstack.voostack.com/s/builderio
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.