Third Party Source Catalog

Third-Party Source Catalog

Use this skill to keep a shared catalog of third-party source trees that multiple agent CLIs can reuse from the same repository.

Quick Start

Run the script from this skill folder:

python3 scripts/source_catalog.py doctor
python3 scripts/source_catalog.py repo add-gh owner/repo --alias short-name
python3 scripts/source_catalog.py repo refresh owner/repo
python3 scripts/source_catalog.py repo fetch owner/repo --tag v1.2.3
python3 scripts/source_catalog.py repo list short-name

If the source was added manually instead of being downloaded by the script:

python3 scripts/source_catalog.py local add /absolute/path/to/source
python3 scripts/source_catalog.py local scan /absolute/path/to/source-parent

The script checks gh and git before every command. If either tool is missing or not configured, fix that first.

Shared Runtime

All agents share the same runtime root by default:

.tmp/third-party-source-catalog/

Important paths under that root:

• state/config.json: bootstrap config used to remember the active runtime root.
• state/catalog.json: catalog records for GitHub and local sources.
• repos//manifest.stub.json: script-owned stub metadata.
• repos//manifest.json: agent-authored enriched manifest.
• repos//sources/: managed downloaded sources.
• repos//archives/: downloaded tag archives.

Change the active runtime root when the user wants the skill to work from another location:

python3 scripts/source_catalog.py config set-root /absolute/path/to/new-root

This updates future operations only. Existing cached data is not moved automatically.

Workflow

1. Run doctor to verify gh authentication and git identity.
2. Register GitHub repos with repo add-gh, or register existing local source trees with local add.
3. Use repo refresh to pull tag metadata from GitHub.
4. Use repo fetch --tag to prefer a tag archive. If the tag does not exist, the script falls back to shallow clone automatically.
5. Use repo list [query] to inspect the catalog or resolve one source path with fuzzy search.
6. Use local scan [path] to discover manually added local source roots under a directory tree.
7. After a source is registered, inspect the code and write manifest.json for the selected repo when richer retrieval metadata is useful.

Commands

• doctor

Validate gh, gh auth status, git, and git config user.name/user.email.

• config show

Print bootstrap and active runtime paths.

• config set-root

Change the active runtime root for future catalog operations.

• repo add-gh [--alias ]

Add or update a GitHub-backed catalog record.

• repo remove

Remove a catalog record and delete only the managed cache under the runtime root.

• repo refresh [ | --all]

Refresh GitHub tag metadata.

• repo list [query]

List all records, or resolve one fuzzy match and print the preferred absolute source path.

• repo fetch [--tag ] [--force]

Download a tag archive when possible, otherwise shallow clone.

• local add [--alias ]

Register one existing local source tree immediately.

• local scan [path] [--max-depth ] [--update-existing]

Discover multiple local source roots recursively.

Manifests

The script creates or updates manifest.stub.json. Treat it as script-owned metadata.

When deeper retrieval context is useful, inspect the source and create manifest.json yourself. Keep it concise and focused on source navigation. Recommended fields:

• summary
• languages
• build_systems
• package_managers
• important_directories
• entry_points_or_public_api
• retrieval_keywords
• notes

The script reads manifest.json when present and does not overwrite it.

Search Rules

• Fuzzy matching uses canonical name, aliases, GitHub name, local folder names, manifest markers, and enriched manifest keywords.
• A unique best match prints full record details and the preferred absolute path.
• Ambiguous matches print candidates so the agent can refine the query.

Local Source Rules

• Prefer local add when the user points to one known source tree.
• Use local scan when the user has manually dropped many source trees into one folder.
• Local git repos try to infer GitHub identity from the origin remote first.
• When no GitHub identity is available, the catalog falls back to folder-based local metadata.
• Recursive scan skips internal cache folders created by this skill.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Tairitsua
• Source: Tairitsua/Monica
• License: MIT
• Homepage: https://monica.dpdns.org/

Install and usage instructions live in the source repository linked above.