Skill Discovery

chimera.skills.discovery discovers reusable agent skills stored as SKILL.md files and injects them into the system prompt.

Skill dataclass

Field	Type	Description
name	str	Unique kebab-case skill identifier
description	str	One-line description (≤ 1 024 chars)
content	str	Full markdown body of the skill file
file_path	str	Absolute path to the SKILL.md file
base_dir	str	Directory containing the file
source	str	Provenance: "chimera" for a native skill, else the foreign source directory (e.g. ~/.codex/skills)

SKILL.md format

---
name: run-tests
description: "Run the project test suite and interpret failures"
---
Use `uv run pytest -x` to run tests. On failure, read the traceback
and propose a minimal fix before re-running.

Name must match ^[a-z0-9][a-z0-9-]{0,63}$. Missing name or description fields cause the file to be silently skipped.

Functions

Function	Description
discover_skills(search_paths)	Walk directories for SKILL.md files; later paths override earlier ones by name
default_search_paths(workdir)	Return the three default skill paths in priority order
discover_all_skills(workdir)	Native skills plus (opt-in) other harnesses’ skills, merged with native winning
discover_foreign_skills(dirs)	Discover skills from other harnesses’ directories, each tagged with its source
resolve_foreign_config()	Read (enabled, allowlist) for the foreign scan from the config chain
default_foreign_skill_dirs()	Return the well-known default foreign-directory allowlist
bundled_algorithms_path()	Return the path to the bundled algorithm skills shipped with the package
format_skills_for_prompt(skills)	Render a ## Available Skills bullet list for system prompt injection
default_remote_cache()	Return ~/.chimera/cache/skills (the default remote cache root)
fetch_remote_index(index_url)	Download and parse a remote index.json skill manifest
download_remote_skills(index_url)	Download every skill from a remote index into the local cache and return them

Search path priority

1. bundled_algorithms_path() — bundled chimera algorithm skills (G12), read-only
2. {workdir}/.chimera/skills/ — project-local
3. ~/.chimera/skills/ — user global

When the same skill name appears in multiple paths, the later path wins. This mirrors the rest of Chimera’s project-over-user precedence model: a project skill named algo-binary-search overrides the bundled version, and a user skill of the same name overrides the project version.

Cross-harness interop (opt-in)

discover_all_skills() extends discovery to also read the skill directories other coding-agent harnesses keep in your home directory — a configurable allowlist that defaults to ~/.claude/skills, ~/.codex/skills, and ~/.agents/skills. It is off by default (a foreign skill’s description would otherwise land in the system prompt unreviewed) and is enabled through the config chain ([skills] scan-foreign = true in ~/.chimera/config.toml) or the CHIMERA_SKILLS_FOREIGN environment variable.

Precedence is project > user Chimera > foreign, and within foreign, allowlist order — a native skill always wins a name collision. Foreign skills are tagged with their source directory so format_skills_for_prompt() can label their provenance. See the cross-harness skill interop guide for the full configuration and precedence reference.

Bundled algorithm skills (G12)

chimera.skills.algorithms ships 13 algorithm cheat-sheet skills covering binary search, dynamic programming, BFS, DFS, hash, two pointers, sliding window, sorting, greedy, recursion, graph traversal, math tricks, and string algorithms. Each lives in its own subdirectory with one SKILL.md, picked up automatically via default_search_paths().

Remote skill index

download_remote_skills() fetches an index.json manifest, downloads each entry’s SKILL.md into a local cache, and returns the freshly-cached Skill list. The expected manifest schema is:

{
  "skills": [
    {"name": "lint-feedback", "description": "...", "url": "https://example.com/skills/lint-feedback/SKILL.md"},
    {"name": "test-coverage", "description": "...", "url": "https://example.com/skills/test-coverage/SKILL.md"}
  ]
}

A bare list ([{...}, ...]) without the envelope is also accepted. Names must match ^[a-z0-9][a-z0-9-]{0,63}$; URLs must use http/https. Individual download failures are skipped so one broken entry never poisons the index.

from chimera.skills.discovery import download_remote_skills

skills = download_remote_skills(
    "https://example.com/chimera-skills/index.json",
    overwrite=False,           # skip skills already cached
    timeout=10.0,
)

Example

from chimera.skills.discovery import discover_skills, default_search_paths, format_skills_for_prompt

skills = discover_skills(default_search_paths("/my/project"))
section = format_skills_for_prompt(skills)
# Inject `section` into the agent system prompt
print(section)
# ## Available Skills
# - **run-tests**: Run the project test suite and interpret failures