|
| 1 | +# codealive-skills — notes for AI coding agents |
| 2 | + |
| 3 | +> Before editing or inspecting a target path, read every applicable `AGENTS.md` from the repository root through the target directory. Do not load instructions from unrelated subtrees. |
| 4 | +
|
| 5 | +This repository ships two things: |
| 6 | + |
| 7 | +1. The **`codealive-context-engine` Agent Skill** — a `SKILL.md` plus a |
| 8 | + set of Python scripts (`scripts/datasources.py`, `search.py`, |
| 9 | + `grep.py`, `fetch.py`, `relationships.py`, `chat.py`). |
| 10 | +2. A **Claude Code plugin** (`.claude-plugin/plugin.json`) that bundles |
| 11 | + the skill with authentication hooks and the |
| 12 | + `codealive-context-explorer` subagent. |
| 13 | + |
| 14 | +## What the skill is NOT |
| 15 | + |
| 16 | +The skill is **not an MCP wrapper** and does **not** expose MCP tools. |
| 17 | +It is a set of Python scripts that call the CodeAlive REST API directly |
| 18 | +over HTTPS, using an API key resolved from the OS credential store or |
| 19 | +the `CODEALIVE_API_KEY` env var. |
| 20 | + |
| 21 | +The [codealive-mcp](https://github.com/CodeAlive-AI/codealive-mcp) |
| 22 | +server is a **separate product** that exposes CodeAlive as MCP tools |
| 23 | +(`get_data_sources`, `semantic_search`, `grep_search`, |
| 24 | +`fetch_artifacts`, `get_artifact_relationships`). The skill and the |
| 25 | +MCP server are parallel integration paths — either works on its own, |
| 26 | +and both can be installed alongside each other. |
| 27 | + |
| 28 | +Do not conflate them when writing or reviewing skill descriptions, |
| 29 | +docs, or commit messages. |
| 30 | + |
| 31 | +## Architecture in one sentence |
| 32 | + |
| 33 | +`SKILL.md` is workflow/trigger metadata; the scripts under |
| 34 | +`skills/codealive-context-engine/scripts/` are the implementation; the |
| 35 | +CodeAlive REST API is the backend. MCP is an optional sibling, not a |
| 36 | +dependency. |
| 37 | + |
| 38 | +## Releasing |
| 39 | + |
| 40 | +1. Edit `SKILL.md`, scripts, or plugin assets. |
| 41 | +2. Bump `.claude-plugin/plugin.json` `version`. |
| 42 | +3. Commit, then annotate a tag matching `vX.Y.Z`. |
| 43 | +4. Push `main` and the tag. CI (`.github/workflows/ci.yml`) runs |
| 44 | + `pytest tests -v` on push. |
| 45 | +5. Users pick up the new version via `claude plugin update |
| 46 | + codealive@codealive-marketplace` or `npx skills update`. |
| 47 | + |
| 48 | +## Writing the skill description |
| 49 | + |
| 50 | +The `description` field in `SKILL.md` frontmatter is how agents decide |
| 51 | +whether to load the skill. Keep it accurate and discoverable: |
| 52 | + |
| 53 | +- Include the word **CodeAlive** so brand mentions match. |
| 54 | +- Include concrete trigger verbs/nouns users actually say: *list data |
| 55 | + sources*, *indexed repositories*, *search across repos*, *fetch |
| 56 | + artifact content*, *call graph*. |
| 57 | +- Do not claim to wrap MCP tools — see above. |
| 58 | +- Do not bake in anti-patterns against specific failure modes of one |
| 59 | + session; the description is read by many agents in many contexts. |
| 60 | +- Hard limit 1024 chars; aim for 300–500. |
0 commit comments