| name | skillify |
| description | Turn any repository into a structured, skill-like decomposition that stays alive for context at all times. Invoke during spec diagramming, brownfield exploration, or at any point in a repo's lifecycle. Auto-creates a skill-pack directory with PROJECT.md (repo-as-skill manifest), context layers, and ADRs. Consumed by /run-project phases automatically. Works on any language.
|
| version | 2.0.0 |
| author | Public Maintainer |
| category | software-development |
| surfaces | ["agent-cli","coding-agent"] |
| tags | ["skillify","organize","context","brownfield","repo-manifest","agent-context","universal"] |
/skillify — Universal Codebase Skillification
One-line pitch
Point it at any repo. Get a .skill-pack/ manifest that turns the repo into a consumable skill for agents. Three context layers, annotated interfaces, inferred ADRs — machine-readable, always fresh, never destructive. Works on Python, JS, Go, Rust, Markdown, monorepos.
Invocation
/skillify [path]
path: Repo path (defaults to .)- Zero flags. All behavior auto-detected:
- Scans the repo live (never reads stale
.run-project/)
- Determines analysis tier from size:
- Surface (<100 LOC): file map + extension distribution
- Shallow (100–2000 LOC): + semantic contracts + entry points
- Deep (>2000 LOC): + import graph, circular deps, deep scores, hotspots
- Writes
.skill-pack/ directory with timestamped snapshots
- Never overwrites destructively — appends with timestamps
When to use it
| Situation | Why |
|---|
Starting /run-project on brownfield | Give the pipeline a pre-built skill manifest |
| During spec diagramming | .skill-pack/PROJECT.md feeds into SEEIT |
| Post-refactor audit | Re-skillify to update context |
| Onboarding a new AI agent | Point it at .skill-pack/PROJECT.md first |
| Any repo that agents need to understand | Reusable context, always current |
What it produces
.skill-pack/
PROJECT.md # Repo-as-skill manifest
context/
structural.json # Module map, import graph, circular deps
semantic.json # Type signatures, contracts, entry points
philosophical.json # Deep scores, hotspots, recommendations
interfaces/
{module}.md # Annotated public API per module
adrs/
adr-{NNN}.md # Inferred architectural decisions
Tiered analysis
| Tier | Trigger | What gets analyzed |
|---|
| Surface | <100 LOC | File map, extensions, module names, basic metadata |
| Shallow | 100–2000 LOC | + AST parsing for Python, function/class signatures, entry points, basic contracts |
| Deep | >2000 LOC | + Full import graph, circular dependency detection, deep module scoring, hotspots, refactoring recommendations |
PROJECT.md format
---
name: inventory
type: service
tier: deep
generated: 2026-05-29T00:51:47Z
---
One-paragraph description auto-inferred from repo name + module names.
| Module | Deep Score | Type | Files |
|--------|-----------|------|-------|
| db | 8.4 | Data layer | 3 files |
| engine | 12.1 | Business logic | 5 files |
- `src/main.py` — CLI entry
- `src/api/app.py` — Web server
- `db` — 4 classes, 2 functions
- `engine` — 7 functions
- No auto-write to external systems
- (Extracted from PRD.md if present)
- Decision-support only
- (Extracted from AGENT_SPEC.md if present)
- `context/structural.json` — machine-readable module map + import graph
- `context/semantic.json` — contracts + entry points
- `context/philosophical.json` — deep scores + hotspots + recommendations
- `adr-001.md` — Language choice
- `adr-002.md` — Database choice
- `adr-003.md` — Web framework
- `adr-004.md` — UI approach
- `adr-005.md` — Plugin architecture (if detected)
- `adr-006.md` — Testing approach
Pipeline integration
/run-project [path]
↓
Phase 1: Grill
↓ detects .skill-pack/ exists
Auto-loads PROJECT.md → module map, boundaries, ADRs
↓ skips redundant questions
Phase 3: Context Layer
↓ reads structural.json, semantic.json, philosophical.json
Feeds into Agent Spec
↓
SEEIT consumes .skill-pack/context/ and .skill-pack/interfaces/
Why .skill-pack/ instead of .run-project/
.run-project/ is pipeline state — phase tracker, evals, handoffs.skill-pack/ is repo identity — the repo's skill manifest, versioned with repo.run-project/ is ephemeral; .skill-pack/ travels with the repo- Both are gitignored; both are regenerated on demand
Re-running for freshness
| Trigger | Action |
|---|
/run-project starts and .skill-pack/ is >7 days old | Auto-re-skillify |
| Major refactor completed | Re-run /skillify |
| 3+ new files or 1 new directory | Re-run |
| New dependencies introduced | Re-run |
| Agent says "I need more context" | Re-run |
Cross-surface behavior
| Surface | How |
|---|
| Agent CLI | Runs scripts/skillify.py directly. Full AST plus git analysis when available. |
| Coding agent | Uses built-in analysis, falls back to skillify.py if available. |
| All | Output format identical. .skill-pack/PROJECT.md is universal entry point. |
Pitfalls
- Execution Focus Rule: When user is mid-execution of a multi-slice project (especially Execute phase), complete the current slice before discussing skill evolution, framework design, or meta-tooling improvements. If the user asks a tangential question, acknowledge briefly, capture it, then ask: "Finish current slice first, or pause to discuss?" User signal to defer: "Wait finish the project first."
- Does not refactor — only surfaces structure. Reorganization is human+agent decision.
- ADRs are inferred — they may reflect pattern, not intent. Human review required.
- Circular deps in tests — not flagged as critical. Only production code cycles matter.
- Orphaned files — some are entry points, CLI scripts, config. Not always bad.
- Interface annotations are best-effort — dynamic languages may lack complete signatures.
- Do not commit
.skill-pack/ — add to .gitignore. It is generated context, not source.
- Deep analysis requires >2000 LOC — smaller repos get surface/shallow tiers.
- Import graph is Python-only today — JS/Go/Rust modules get surface tier.
- Multi-store schema propagation: When adding store awareness to an existing schema, include
store_id in every table that has store-scoped data. Add Store table for locations. This affects downstream ABC classification, inventory snapshots, recommendations, and sync jobs.
Version history
- v2.0.0 (2026-05-29): Tiered analysis (surface/shallow/deep). Live repo scanning (never stale). Universal language support. FastAPI/Flask/Django detection. HTMX/React/Vue detection. Timestamped snapshots. Deep module scoring with hotspot detection.
- v1.0.0 (2026-05-28): Initial universal repo skillification. PROJECT.md manifest. .skill-pack/ directory. Inferred ADRs. Interface annotation. Auto-integration with /run-project.
References
references/dual-persistence-convention.md — Full explanation of .run-project/ vs .skill-pack/ distinction, when to use each, when to re-run, migration notes from pre-2026-05-28 conventions.
