# Generate Skills From Knowledge

> Turn one or more knowledge documents into a provider-agnostic Agent Skills bundle (SKILL.md + examples/templates), using a plan -> apply -> lint workflow.

- Skill: `willyu1007/generate-skills-from-knowledge` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds add willyu1007/generate-skills-from-knowledge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/willyu1007/generate-skills-from-knowledge/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: willyu1007 (https://skillmd.com/u/willyu1007)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/willyu1007/generate-skills-from-knowledge

---


# Generate Skills from Knowledge Documents

## Purpose
Convert existing knowledge docs (one or many) into **discoverable, reusable Agent Skills** that follow a consistent, lintable structure and **progressive disclosure**.

The generate-skills-from-knowledge skill is provider-agnostic: the output is plain folders + `SKILL.md` files and can be consumed by any agent runtime that discovers skills from the filesystem.

## When to use
Use the generate-skills-from-knowledge skill when you have:
- A set of Markdown/text docs that describe **how work should be done**, and you want to convert them into skills.
- Legacy "how-to" docs that are too long or too project-specific and need to become **portable** skills.
- Multiple docs with overlapping guidance and you want to **split/merge** them into capability-oriented skills.

Do not use the skill when:
- The source material is confidential and cannot be copied into a work area.
- You only need a quick summary; you do not need reusable procedures.

## Inputs
You MUST provide:
- **Source documents**: one or more file paths (prefer Markdown). If not Markdown, provide a plain-text export.
- **Output target**:
  - `skills_root` (directory where the generated skills will be written), OR
  - a writable working directory to create a standalone skills bundle.
- **Portability constraints**:
  - whether to remove provider-specific terms,
  - whether project paths/scripts should be generalized,
  - any allowed exceptions (for example, "dev-docs may keep repo-specific layout").

You SHOULD provide:
- Desired **taxonomy** (optional): up to two tiers (e.g., `backend/common`, `frontend/components`, `workflows/common`).
- Existing naming conventions for skill names (kebab-case verb + domain).

## Outputs
The expected outputs are:
- A set of skill directories, each containing:
  - `SKILL.md` (required)
  - `reference.md` (optional, for deep details)
  - `examples/` (optional, scenario-specific examples)
  - `templates/` (optional, reusable snippets/skeletons)
- A `CONVERSION_REPORT.md` summarizing:
  - source documents
  - created/updated skills
  - split/merge operations
  - known limitations / follow-ups
- A lint report (stdout) from `python3 ./scripts/skillgen.py lint ...` (recommended)

## Command working directory
All relative paths in commands (for example `./scripts/skillgen.py` and `./templates/...`) are relative to:
- `.ai/skills/workflows/skill-operation/generate-skills-from-knowledge/`

## Steps
### Scenario A: Convert docs into a skills bundle (recommended default)
1. **Inventory** the source docs (file list) and decide what is IN/OUT of scope.
2. **Derive candidate skills**:
   - one skill should map to one capability (not one file),
   - split long docs into multiple skills by trigger/intent,
   - merge overlapping docs when they solve the same intent.
3. Create a **conversion plan** using `./templates/conversion-plan.schema.json`:
   - define the skills to create,
   - map each skill to its source docs,
   - define which examples/templates to extract.
4. Review the plan and obtain approval before writing files:
   - confirm the skill taxonomy and naming
   - confirm portability constraints (remove provider/project specifics)
   - confirm what will be created vs updated
5. Run:
   - `python3 ./scripts/skillgen.py apply --plan <plan.json>` to scaffold the skill directories.
6. For each generated skill:
   - rewrite `SKILL.md` to be **high-signal and short**,
   - move large examples into `examples/`,
   - move reusable snippets into `templates/`,
   - put deep rationale into `reference.md`,
   - remove cross-skill links ("See also", "Related docs").
7. Run:
   - `python3 ./scripts/skillgen.py lint --skills-root <skills_root>` and fix issues until clean.
8. Package the bundle (optional):
   - `python3 ./scripts/skillgen.py package --skills-root <skills_root> --out <bundle.zip>`

### Scenario B: Convert docs directly into a repository skills root
Follow Scenario A, but set `skills_root` to the repository's skills SSOT directory.

If your repo has additional syncing rules (provider stubs, monorepo layouts), treat those as **outside** the scope; the skill only produces the SSOT-format skills.

## Boundaries
- You MUST NOT include secrets, credentials, or internal-only URLs in generated skills.
- You MUST NOT copy large logs or whole source documents verbatim into `SKILL.md`.
- You SHOULD avoid hard-coded repository paths unless the target is explicitly "dev-docs" with a known layout.
- You MUST keep each `SKILL.md` <= 500 lines by moving detail into `reference.md`, `examples/`, and `templates/`.

## Verification
Run the linter and confirm:
- the conversion plan was reviewed and approved before applying
- every skill directory contains `SKILL.md` with valid YAML frontmatter
- `name` matches the directory name
- no `resources/` directories exist
- `SKILL.md` line count is within limits
- examples/templates live under `examples/` and `templates/` rather than bloating `SKILL.md`
- cross-skill relative links (e.g., `../<other-skill>`) are absent

## Included assets
- `./scripts/skillgen.py`: plan/apply/lint/package helper
- `./scripts/init_skill.py`: optional helper to scaffold a new skill directory
- `./templates/conversion-plan.schema.json`: JSON Schema for a conversion plan
- `./templates/conversion-plan.example.json`: example plan
- `./templates/skill-skeleton/SKILL.md`: copy/pasteable skeleton for manual skill authoring
- `./examples/quickstart.md`: end-to-end usage example
- `./examples/plan-writing-guide.md`: how to write a good plan for an LLM