# Skill Management

> Design, inspect, create, update, and validate Hone skills, including Codex-native discovery through workspace .agents/skills and compatibility with legacy Hone runners.

- Skill: `b-m-capital-research/skill-management` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add b-m-capital-research/skill-management`
- Raw SKILL.md: https://api.skillmd.com/api/skills/b-m-capital-research/skill-management/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: b-m-capital-research (https://skillmd.com/u/b-m-capital-research)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/b-m-capital-research/skill-management

---


## Skill Management (skill_manager)

Manage the source skill, not a generated projection of it.

## Runtime Contract

1. Built-in sources live in `skills/<id>/SKILL.md`; custom sources live in `data/custom_skills/<id>/SKILL.md`; legacy project-local sources may live in a closer `.hone/skills/<id>/SKILL.md`.
2. Trusted persistent Codex ACP workspaces expose enabled Hone skills as individual symlinks under `<actor workspace>/.agents/skills/`.
3. Codex performs native progressive disclosure: it starts with each skill's name, description, and path, then reads the complete `SKILL.md` only when the task activates that skill.
4. Do not copy skill bodies into each Codex user turn and do not call Hone MCP skill-loading tools merely to activate a skill.
5. Non-Codex and strict legacy runners retain Hone's `discover_skills` / `skill_tool` bridge. `load_skill` remains a compatibility shim only.

## Frontmatter Contract

Prefer this frontmatter schema:

```yaml
---
name: Human readable name
description: One-line description
when_to_use: Brief trigger guidance
allowed-tools:
  - skill_tool
user-invocable: true
model: optional model override
effort: optional effort override
context: inline
agent: optional agent hint
paths:
  - src/**/*.rs
hooks: {}
arguments: []
script: optional default script path like scripts/run.sh
shell: optional shell hint
---
```

Notes:

- `allowed-tools` replaces legacy `tools` as the main runtime field.
- `context` should usually be `inline`; use `fork` only when the skill should run in an isolated child runner.
- `paths` hides the skill from the default listing until the active task touches matching files.
- `script` declares the default executable entrypoint inside the skill directory. Native Codex may run a trusted bundled script directly; legacy Hone runners may use `skill_tool(..., execute_script=true)`.
- Keep the Markdown body task-oriented and ready to inject as prompt text.

## How To Inspect Skills

On native Codex:

1. Use the native skill list already supplied by Codex.
2. Match from `name` and `description`.
3. Read the selected skill's `SKILL.md` from its disclosed path.
4. Read bundled scripts or references only when the task needs them.

On a legacy Hone runner without native skill discovery:

1. Use `discover_skills(query="...")` to select the skill.
2. Use `skill_tool(skill_name="<skill id>")` to load its full prompt.

## How To Create Or Update Skills

1. Collect the intended skill id, description, trigger conditions, and whether users should be able to invoke it directly with `/<skill-name>`.
2. Write or update the source `SKILL.md`; never edit the actor-workspace symlink as if it were an independent copy.
3. Keep the body concrete: trigger rules, required steps, tool usage expectations, and refusal/verification constraints.
4. Validate native discovery with Codex `skills/list` or a real Codex ACP turn. Validate the legacy bridge separately only when that runner remains in scope.

## Strict Rules

- On native Codex, do not call `discover_skills`, `load_skill`, or `skill_tool` just to discover or load a skill.
- Preserve actor-owned entries in `.agents/skills`; Hone only owns its `hone__*` links.
- Do not teach the deprecated `skill_tool(action="add" | "update" | "remove")` CRUD workflow.
- Do not rely on `load_skill` as the main user-facing path.
- If a skill is path-gated, mention that it may stay hidden until matching files are involved.
- If runtime enforcement is not implemented for a field such as `hooks` or strict tool scoping, say so plainly instead of pretending it is active.