Content
# Enterprise Skill Management Hub
An enterprise platform for managing AI agent skills, MCP servers, and A2A agents with layered access control, LLM-powered scanning, a Claude-powered agent playground, and smart tool discovery — all backed by [AWS Bedrock AgentCore Registry](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/registry.html) in **us-east-1**.
---
## Design Overview
The platform solves three enterprise problems:
1. **Skill sprawl** — Teams build MCP servers, agents, and skills independently. Without a central catalog, resources stay siloed and get duplicated. This hub provides a single registry with approval workflows.
2. **Access control** — Not every team should see every tool. The hub enforces layered visibility: company-wide, department-scoped, individual-only, and grant-based sharing to specific teams or people.
3. **Quality and security** — External skills and internal tools need vetting before enterprise deployment. Claude Sonnet 4.6 analyzes actual skill content for security risks, license issues, and compliance gaps.
### Key Personas (from AgentCore Registry)
| Persona | Role in Hub | What they do |
|---------------|--------------------|-----------------------------------------------------------------|
| Administrator | Company Admin | Create registries, set policies, approve/reject skills |
| Publisher | Any user | Create skills, import external MCP/skills, submit for approval |
| Curator | Dept Admin | Review and approve skills within their scope |
| Consumer | Individual | Discover and use approved skills in the agent playground |
---
## Architecture
```
┌──────────────────────────────────────────────────────────────────────────────┐
│ Frontend (React 18 + Vite 6) │
│ │
│ Login Dashboard Skills Playground Registries Scanning Sharing Settings│
│ │ │ │ │
│ skill detail Claude chat LLM scan │
│ + AWS record + skill control + findings │
│ contents + smart select │
└──────────────────────────────┬───────────────────────────────────────────────┘
│ REST / JSON + JWT auth
┌──────────────────────────────▼───────────────────────────────────────────────┐
│ Backend (FastAPI + Python 3.12) │
│ │
│ 9 routers: │
│ auth │ skills │ registries │ playground │ scanning │ sharing │ users │ ... │
│ │
│ visibility.py ── centralized access control ────────────────────────────── │
│ │ 1. Company admin → sees all │
│ │ 2. Publisher → sees own skills │
│ │ 3. visibility="company" → everyone sees │
│ │ 4. visibility="department" → same dept sees │
│ │ 5. SkillGrant(department_id) → shared dept sees │
│ │ 6. SkillGrant(user_id) → specific user sees │
└──────┬──────────────┬────────────────────┬───────────────────────────────────┘
│ │ │
┌──────▼──────┐ ┌─────▼────────────┐ ┌────▼──────────────────────────────────┐
│ PostgreSQL │ │ Bedrock Runtime │ │ Bedrock AgentCore (us-east-1) │
│ 16 │ │ (us-east-1) │ │ │
│ │ │ │ │ Control Plane (bedrock-agentcore-ctrl) │
│ 8 tables: │ │ Claude Sonnet │ │ ├─ CreateRegistry / ListRegistries │
│ companies │ │ 4.6 via │ │ ├─ CreateRegistryRecord │
│ departments │ │ inference │ │ ├─ SubmitRegistryRecordForApproval │
│ users │ │ profile │ │ ├─ UpdateRegistryRecordStatus │
│ skills │ │ │ │ └─ GetRegistryRecord (full content) │
│ skill_grants│ │ Used for: │ │ │
│ registries │ │ • Scanning │ │ Data Plane (bedrock-agentcore) │
│ scan_results│ │ • Playground │ │ └─ SearchRegistryRecords │
│ share_reqs │ │ agent chat │ │ (semantic + keyword hybrid search) │
└─────────────┘ └──────────────────┘ │ │
│ + GitHub API (external skill import) │
└───────────────────────────────────────┘
```
### Tech Stack
| Layer | Technology |
|------------|------------------------------------------------------------------|
| Frontend | React 18, TypeScript, Tailwind CSS 3, Vite 6, React Router, Lucide icons |
| Backend | Python 3.12, FastAPI, SQLAlchemy 2, Pydantic 2, boto3 |
| Database | PostgreSQL 16 |
| AI/LLM | Bedrock Claude Sonnet 4.6 (`us.anthropic.claude-sonnet-4-6`) |
| Registry | AWS Bedrock AgentCore Registry (us-east-1, IAM-authorized) |
| Auth | JWT (python-jose), SHA-256 password hashing (demo) |
### Data Model
```
Company 1──* Department 1──* User
│ │ │
│ │ ├── publishes ──* Skill
│ │ │ │
│ │ │ ├── aws_record_id → AgentCore Registry Record
│ │ │ ├── 1──* ScanResult
│ │ │ ├── 1──* ShareRequest (target_dept_ids[], target_user_ids[])
│ │ │ └── 1──* SkillGrant (dept or user)
│ │ │
└──* Registry ─┘ └── share_requests, skill_grants
```
---
## Features
### 1. Layered Access Control
| Condition | Example |
|-----------|---------|
| Company admin sees all | `admin` sees 14 skills |
| Publisher sees own | `dev1` sees `doc-generator` (visibility=individual, own skill) |
| Company-wide | Everyone sees `code-review-mcp` (visibility=company) |
| Same department | DS team sees `data-pipeline-agent` (visibility=department, DS dept) |
| Department grant | Engineering sees `incident-response-agent` (shared from Security→Eng) |
| Individual grant | `dev1` sees `vulnerability-scanner` (shared to dev1 specifically) |
Enforced by `visibility.py` — a single module used by skill list, skill detail, AWS record view, and playground.
### 2. Multi-Target Cross-Team Sharing
Share a skill with multiple departments AND individual users in one request:
- Checkbox grid for departments and users in the share modal
- Admin approval creates `SkillGrant` rows for each target
- Shared skills appear in the target's list without changing base visibility
- Example: Security shares `vulnerability-scanner` to dev1 and dev2 specifically (not the whole Engineering team)
### 3. Approval Workflow (synced to AWS)
```
DRAFT → PENDING_APPROVAL → APPROVED / REJECTED / DEPRECATED
│ │ │ │ │
│ SubmitRegistry UpdateRegistry UpdateRegistry
│ RecordForApproval RecordStatus RecordStatus
│ │ (APPROVED) (REJECTED)
└── CreateRegistryRecord
```
Every status change pushes to AWS AgentCore Registry. Status syncs back from AWS on detail view and bulk sync.
### 4. AWS AgentCore Registry Integration
Every skill is a real registry record in us-east-1:
| Skill Type | Registry Record Type | Descriptor Content |
|-------------|---------------------|--------------------|
| MCP Server | `MCP` | Server definition with tool schemas |
| A2A Agent | `A2A` | Agent card (protocol v0.3) with capabilities |
| Skill | `AGENT_SKILLS` | Full skill markdown documentation |
The skill detail page fetches and displays the full AWS record content:
- **MCP**: Server name, version, and each tool with description and input schema
- **A2A**: Protocol version, agent URL, and each capability
- **Skills**: Full markdown documentation (collapsible, shows size)
- **Raw JSON**: Toggle to see the complete descriptor
### 5. Import External Skills from GitHub
Any user can import external MCP servers and skills:
1. Paste a GitHub URL (e.g. `https://github.com/anthropics/skills/tree/main/skills/pdf`)
2. System fetches `SKILL.md` via GitHub API, parses YAML frontmatter
3. Fetches extra reference files (`reference.md`, `forms.md`)
4. Publishes full content to AgentCore Registry (not a stub)
5. Starts as `DRAFT` — needs admin approval before others can use it
### 6. LLM-Powered Security Scanning (Claude Sonnet 4.6)
Claude reads the actual skill content and returns structured findings:
| Scan Type | What Claude Analyzes |
|---------------|---------------------|
| Security | Hardcoded secrets, input validation, injection risks, unsafe patterns, dependency risks |
| Compliance | GDPR/HIPAA/SOC2 data handling, audit logging, access controls |
| Compatibility | Protocol version, schema validation, dependency conflicts |
| License | License type, copyleft risk, dependency licenses, export control |
Real example — scanning the `pdf` skill from Anthropic:
- Security: 38% (found hardcoded passwords in examples, no input validation, path traversal risks)
- License: 48% (proprietary license, GPL dependencies like poppler/pdftk, export control concerns with encryption)
Falls back to rule-based scanning if Bedrock is unavailable.
### 7. Agent Playground (Claude Sonnet 4.6)
Chat with an AI agent that uses your approved enterprise skills as tools:
- Claude receives a system prompt listing enabled skills with their tools and documentation
- Toggle skills on/off from the side panel — only your visible approved skills appear
- Conversation history maintained across turns
- Tool invocation tracing shows which skills Claude referenced
- Disabling a skill removes it from Claude's context entirely
### 8. Smart Tool Selection (AgentCore Registry Search)
When many skills are enabled, the system prompt gets large. Smart Select solves this:
1. User sends "Check my code for security vulnerabilities"
2. Backend calls `SearchRegistryRecords` with the message as a semantic query
3. Registry returns top 5 relevant records (e.g. `vulnerability-scanner`, `code-review-mcp`)
4. Only matched skills are sent to Claude (3 instead of 14, 5 tools instead of 32)
Uses AgentCore Registry's built-in hybrid search (semantic + keyword) — no pgvector needed.
Toggle in the playground header. ON by default.
---
## Project Structure
```
enterprise-skill-hub/
├── backend/
│ ├── main.py # FastAPI app entry point, router registration, startup seeds
│ ├── database.py # PostgreSQL connection via SQLAlchemy
│ ├── models.py # 8 ORM models: Company, Department, User, Skill, SkillGrant, ...
│ ├── schemas.py # Pydantic request/response schemas
│ ├── auth_utils.py # JWT creation/validation, password hashing, RBAC helpers
│ ├── visibility.py # Centralized 6-condition skill visibility query
│ ├── aws_registry.py # boto3 wrapper: registry CRUD, record CRUD, search
│ ├── bedrock_llm.py # Claude Sonnet 4.6 client (invoke_claude, invoke_claude_json)
│ ├── github_fetcher.py # GitHub API: fetch SKILL.md, parse frontmatter, get extra files
│ ├── seed.py # Demo data: 6 teams, 12 users, 14 skills, 10 grants
│ ├── seed_aws.py # Publishes seed skills to AWS AgentCore Registry
│ ├── requirements.txt
│ └── routers/
│ ├── auth.py # Login + current user
│ ├── companies.py # Company CRUD + policy toggle
│ ├── departments.py # Department CRUD
│ ├── users.py # User CRUD
│ ├── skills.py # Skill CRUD + approval + AWS sync + import + AWS record detail
│ ├── registries.py # Registry CRUD + AWS pass-through + record management
│ ├── scanning.py # LLM-powered 4-dimension scanning via Claude
│ ├── sharing.py # Multi-target sharing + SkillGrant management
│ └── playground.py # Claude agent chat + smart tool selection
├── frontend/
│ ├── index.html
│ ├── package.json # React 18, Tailwind, Vite 6, Lucide
│ ├── vite.config.ts # Dev proxy /api → localhost:8000
│ ├── tailwind.config.js
│ ├── tsconfig.json
│ └── src/
│ ├── main.tsx # React entry point
│ ├── App.tsx # Routes + AuthContext
│ ├── api.ts # 30+ API client functions
│ ├── types.ts # TypeScript interfaces matching backend schemas
│ ├── index.css # Tailwind imports
│ ├── components/
│ │ └── Layout.tsx # Sidebar nav + header + user profile
│ └── pages/
│ ├── LoginPage.tsx # Login form + 12 demo quick-login buttons
│ ├── DashboardPage.tsx # Stats cards + type chart + activity feed
│ ├── SkillsPage.tsx # Skill grid + 5 filters + create/import modals
│ ├── SkillDetailPage.tsx # Detail + AWS record content + scans
│ ├── PlaygroundPage.tsx # Claude chat + skill control + smart select
│ ├── RegistriesPage.tsx # Registry cards + records + create forms
│ ├── ScanningPage.tsx # Scan runner + score rings + findings
│ ├── SharingPage.tsx # Multi-target sharing table + create modal
│ └── SettingsPage.tsx # Company policy + departments + users
└── README.md
```
---
## API Reference
### Authentication
| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/auth/login` | Login → JWT token + user |
| GET | `/api/auth/me` | Current user profile |
### Skills
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/skills/dashboard/stats` | Dashboard statistics |
| POST | `/api/skills/sync-aws` | Bulk sync all AWS statuses |
| POST | `/api/skills/import-external` | Import from GitHub URL (any user, starts as draft) |
| GET | `/api/skills/` | List skills (visibility-filtered; params: status, skill_type, source, publisher_id, search) |
| POST | `/api/skills/` | Create skill + publish to AWS |
| GET | `/api/skills/{id}` | Skill detail (visibility-checked, syncs AWS status) |
| GET | `/api/skills/{id}/aws-record` | Full AWS registry record with parsed descriptors |
| PUT | `/api/skills/{id}` | Update metadata |
| PUT | `/api/skills/{id}/status` | Change status (syncs to AWS) |
| DELETE | `/api/skills/{id}` | Delete skill + AWS record |
### Agent Playground
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/playground/available-skills` | Approved skills visible to user |
| POST | `/api/playground/chat` | Chat with Claude (body: message, enabled_skill_ids, history, smart_select) |
### Scanning
| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/scanning/scan` | Run LLM scan (body: skill_id, scan_types[]) |
| GET | `/api/scanning/skill/{id}` | Scan results for a skill |
| GET | `/api/scanning/summary/{id}` | Latest scan summary per type |
### Sharing
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/sharing/` | List share requests (visibility-filtered) |
| POST | `/api/sharing/` | Create share request (body: skill_id, target_department_ids[], target_user_ids[], message) |
| PUT | `/api/sharing/{id}` | Approve/reject → creates SkillGrant entries |
| GET | `/api/sharing/grants/{skill_id}` | List grants for a skill |
### Registries
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/registries/` | List (refreshes from AWS) |
| POST | `/api/registries/` | Create in AWS (admin only) |
| PUT | `/api/registries/{id}` | Update in AWS |
| DELETE | `/api/registries/{id}` | Delete from AWS |
| POST | `/api/registries/sync` | Pull all AWS registries to local DB |
| GET | `/api/registries/{id}/records` | List AWS records |
| POST | `/api/registries/{id}/records` | Create AWS record |
| POST | `/api/registries/{id}/records/{rid}/submit` | Submit for approval |
| PUT | `/api/registries/{id}/records/{rid}/status` | Approve/reject/deprecate |
| DELETE | `/api/registries/{id}/records/{rid}` | Delete record |
### Other
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/users/` | List users |
| GET | `/api/departments/` | List departments |
| PUT | `/api/companies/{id}` | Update company policy |
| GET | `/api/health` | Health check |
---
## Deployment
### Prerequisites
- Python 3.12+
- Node.js 18+
- PostgreSQL 16+
- AWS account with:
- Bedrock AgentCore access in us-east-1 (Registry API)
- Bedrock Runtime access in us-east-1 (Claude Sonnet 4.6 inference profile)
- AWS credentials configured (`~/.aws/credentials` or environment variables)
### Step 1: PostgreSQL
```bash
# Install (Amazon Linux 2023)
sudo dnf install -y postgresql16-server postgresql16
# Initialize and start
sudo postgresql-setup --initdb
sudo systemctl start postgresql
sudo systemctl enable postgresql
# Allow password auth
sudo sed -i 's/ident$/md5/g' /var/lib/pgsql/data/pg_hba.conf
sudo systemctl restart postgresql
# Create database and user
sudo -u postgres psql -c "CREATE USER skillhub WITH PASSWORD 'skillhub123' CREATEDB;"
sudo -u postgres psql -c "CREATE DATABASE skill_hub OWNER skillhub;"
```
### Step 2: AWS Credentials
```bash
aws configure
# Region: us-east-1
```
Required IAM permissions:
```json
{
"Effect": "Allow",
"Action": [
"bedrock-agentcore:CreateRegistry",
"bedrock-agentcore:ListRegistries",
"bedrock-agentcore:GetRegistry",
"bedrock-agentcore:UpdateRegistry",
"bedrock-agentcore:DeleteRegistry",
"bedrock-agentcore:CreateRegistryRecord",
"bedrock-agentcore:ListRegistryRecords",
"bedrock-agentcore:GetRegistryRecord",
"bedrock-agentcore:UpdateRegistryRecordStatus",
"bedrock-agentcore:SubmitRegistryRecordForApproval",
"bedrock-agentcore:DeleteRegistryRecord",
"bedrock-agentcore:SearchRegistryRecords",
"bedrock:InvokeModel"
],
"Resource": "*"
}
```
### Step 3: Backend
```bash
cd backend
pip install -r requirements.txt
# First run seeds demo data + publishes to AWS AgentCore Registry
python main.py
# → http://localhost:8000
# → Swagger docs: http://localhost:8000/docs
```
### Step 4: Frontend
```bash
cd frontend
npm install
npm run dev
# → http://localhost:5173
```
### Production Deployment
```bash
# Backend: gunicorn with uvicorn workers
pip install gunicorn
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000
# Frontend: build static files
npm run build # → dist/
# Serve with nginx, CloudFront, S3, or any static host
# Database: use managed PostgreSQL (RDS, Aurora)
# Update SQLALCHEMY_DATABASE_URL in backend/database.py
# Security: replace SHA-256 with bcrypt/argon2, use a real JWT SECRET_KEY
```
---
## User Guide
### Demo Accounts
| Username | Password | Role | Department | Sees |
|--------------|-------------|-----------------|--------------|---------------------------------------------------------------|
| admin | admin123 | Company Admin | Engineering | All 14 skills |
| eng_lead | eng123 | Dept Admin | Engineering | Eng dept + company-wide + shared to Eng |
| ds_lead | ds123 | Dept Admin | Data Science | DS dept + company-wide + shared to DS + deploy (individual) |
| sec_lead | sec123 | Dept Admin | Security | Sec dept + company-wide + shared to Sec |
| ops_lead | ops123 | Dept Admin | Operations | Ops dept + company-wide + shared to Ops + ml-monitor (individual) |
| pm_lead | pm123 | Dept Admin | Product | Product dept + company-wide + shared to Product |
| dev1 | dev123 | Individual | Engineering | Own + Eng dept + company-wide + shared to Eng + vuln-scanner (individual) |
| dev2 | dev123 | Individual | Engineering | Own + Eng dept + company-wide + shared to Eng + vuln-scanner (individual) |
| analyst | analyst123 | Individual | Data Science | Own + DS dept + company-wide + shared to DS |
| ml_eng | ml123 | Individual | Data Science | Own + DS dept + company-wide + shared to DS |
| sec_analyst | sec123 | Individual | Security | Own + Sec dept + company-wide + shared to Sec |
| fin_analyst | fin123 | Individual | Finance | Own + Finance dept + company-wide + shared to Finance |
### Pre-configured Cross-Team Shares
| Skill | From | Shared With |
|-------------------------|--------------|--------------------------------------------|
| sql-query-optimizer | Engineering | Data Science (dept) + Finance (dept) |
| incident-response-agent | Security | Engineering (dept) + Operations (dept) |
| deploy-orchestrator | Operations | Engineering (dept) + Carol Data (user) |
| ml-model-monitor | Data Science | Security (dept) + Fiona Ops (user) |
| vulnerability-scanner | Security | Dave Developer (user) + Helen Hacker (user)|
| infra-cost-analyzer | Operations | Finance (dept) + Product (dept) |
### Workflow: Publish an Internal Skill
1. Log in as any user → **Skills** → **Publish Skill**
2. Fill name, type (MCP Server / A2A Agent / Skill), description
3. Skill created as `DRAFT` + published to AWS AgentCore Registry
4. Click **Submit** → `PENDING_APPROVAL` (AWS: `SubmitRegistryRecordForApproval`)
5. Admin clicks **Approve** → `APPROVED` (AWS: `UpdateRegistryRecordStatus`)
6. Skill now visible to users based on its visibility setting
### Workflow: Import External Skill from GitHub
1. Log in as any user → **Skills** → **Import External**
2. Paste URL: `https://github.com/anthropics/skills/tree/main/skills/pdf`
3. System fetches SKILL.md + reference files via GitHub API
4. Full content published to AgentCore Registry
5. Starts as `DRAFT` — admin must approve before others can use it
### Workflow: Share a Skill Across Teams
1. **Sharing** → **Share Skill**
2. Select skill, check target departments and/or individual users
3. Add a message explaining why
4. Admin reviews → **Approve** creates `SkillGrant` entries
5. Targets now see the skill in their list and playground
### Workflow: View Skill Registry Content
1. Click any skill → detail page
2. **AgentCore Registry Record** section shows:
- MCP: server definition + each tool with description and input schema
- A2A: agent card + each capability
- Skill: full markdown documentation (collapsible)
3. Toggle **Raw Descriptor JSON** for the complete data
4. All users see content for skills they have access to
### Workflow: Run a Security Scan
1. **Scanning** → select a skill → click play
2. Claude Sonnet 4.6 analyzes the actual skill content
3. Returns structured findings per dimension (Security, Compliance, Compatibility, License)
4. Each finding has severity (critical/high/medium/low/info) and explanation
### Workflow: Use the Agent Playground
1. **Agent Playground** → only your visible approved skills appear in the side panel
2. Toggle skills on/off to control what the agent can use
3. **Smart Select** (ON by default): AgentCore Registry semantic search auto-selects relevant tools per message
4. Chat with Claude — it uses enabled skills as context and references them in responses
5. Expand **tool invocations** to see which skills were used
6. Expand **thinking** to see the agent's reasoning trace
### Workflow: Test Visibility
1. Log in as `dev1` → see 8 skills (own + dept + company-wide + shared)
2. Log in as `fin_analyst` → see 5 skills (own + company-wide + shared to Finance)
3. Log in as `admin` → see all 14 skills
4. Each user's playground only shows skills they can access
---
## Configuration
| Setting | File | Default |
|----------------------|----------------------------|--------------------------------------------|
| Database URL | `backend/database.py` | `postgresql://skillhub:skillhub123@localhost:5432/skill_hub` |
| AWS Region | `backend/aws_registry.py` | `us-east-1` |
| LLM Model | `backend/bedrock_llm.py` | `us.anthropic.claude-sonnet-4-6` |
| JWT Secret | `backend/auth_utils.py` | Demo key (change for production) |
| JWT Expiry | `backend/auth_utils.py` | 480 minutes |
| CORS Origins | `backend/main.py` | `localhost:5173`, `localhost:3000` |
| API Proxy | `frontend/vite.config.ts` | `/api` → `localhost:8000` |
