Related Pages

Related topics: Agent Skills Format & Repository Structure, Prokerala Astrology API Skill, Prokerala PHP SDK Skill

Repository Overview

The prokerala/agent-skills repository is a curated collection of "skills" packaged for consumption by AI agents and developer tooling. Each skill is an autonomous, self-describing bundle that documents a specific Prokerala capability (for example, an API or SDK) and enables agents to reason about when and how to invoke it. The repository functions as the canonical source of truth from which a rolling release artifact is built and redistributed on every push to the default branch.

Purpose and Scope

The repository exists to bridge Prokerala's developer-facing products and the emerging ecosystem of agent-driven development. Rather than scattering integration knowledge across READMEs, wikis, and forum posts, every capability is captured as a discrete SKILL.md file alongside the supporting metadata required for an agent runtime to discover, version, and load it. Source: README.md:1-40

Key properties of the repository:

• Agent-oriented packaging — Each top-level directory under the repository root represents a single skill, exposed through a SKILL.md entry point that follows an agent-readable format.
• Multi-product coverage — Skills span the company's product surface, including REST APIs (for example, the astrology API) and language-specific SDKs (for example, the PHP SDK), allowing agents to recommend the most appropriate integration path.
• Source of a rolling release — The repository's main branch feeds an automated build pipeline that publishes a content-addressed archive, enabling reproducible consumption without checking out the repository.

Repository Structure

The repository follows a flat, skill-per-directory layout. There is no shared runtime code; each skill is independent and can be added or removed without affecting the others. Source: README.md:1-40

This structure makes the repository easy to navigate for human contributors and trivially indexable by automated tooling. Each skill directory is intentionally minimal so that an agent can ingest it without parsing framework-specific scaffolding.

Skill Format and Discovery

Every skill in the repository conforms to a common shape: a SKILL.md file that describes the capability, its inputs, outputs, authentication model, and code examples. This uniform contract is what allows heterogeneous skills — a REST API and an SDK, for instance — to be loaded side by side into the same agent context. Source: prokerala-astrology-api/SKILL.md:1-40

For API-focused skills, the document typically enumerates the base URL, request/response shape, and the authentication header that callers must supply. For SDK-focused skills, the document typically enumerates the package name, the supported PHP/Python/Node version range, and the constructor signature. Source: prokerala-sdk-php/SKILL.md:1-40

By isolating integration knowledge inside SKILL.md, the project keeps the skills portable: the same document can be rendered as documentation for humans or parsed as structured metadata by an agent runtime.

Release and Distribution Model

Distribution is handled through GitHub Releases with a single, stable entry point that always reflects the latest build of the default branch. The community context confirms the following contract:

• Stable index URL — https://github.com/prokerala/agent-skills/releases/download/latest/index.json is the only URL clients need to hard-code; the rolling-release tag is rewired on every push. Source: community_context
• Content-addressed assets — Each skill archive is named <skill>-<digest>.zip, where the digest identifies the exact contents of that build. This guarantees that a given URL always resolves to the same bytes and that consumers can cache aggressively. Source: community_context
• Index-driven discovery — The index.json manifest enumerates the available skills and references their corresponding <skill>-<digest>.zip assets, allowing clients to download only what they need. Source: community_context

flowchart LR
    A[main branch push] --> B[Build pipeline]
    B --> C[index.json]
    B --> D[skill-a-digest.zip]
    B --> E[skill-b-digest.zip]
    C --> F[Agent runtime]
    D --> F
    E --> F

This model decouples consumers from Git history: clients always fetch the latest stable manifest, resolve the digests they care about, and download immutable archives, which simplifies caching, verification, and rollback.

Contributing and Extending

Contributors add a new skill by creating a directory at the repository root and dropping in a SKILL.md that follows the existing contract. Because the release pipeline is content-addressed, adding or modifying a skill automatically produces a new digest and a refreshed index.json on the next push to main — no manual versioning is required. Source: README.md:1-40

This low-friction contribution model is the primary reason the repository can grow alongside Prokerala's product roadmap: every new API, SDK, or integration pattern can be exposed to agents as soon as its SKILL.md lands on main.

Related Topics

If you want to learn how a specific skill is consumed once it is published, see the per-skill pages such as prokerala-astrology-api and prokerala-sdk-php, which document the exact endpoints, packages, and code patterns each skill describes. For the redistribution terms that govern the rolling release and its assets, consult the LICENSE file at the repository root.

Related Pages

Related topics: Repository Overview

Agent Skills Format & Repository Structure

The prokerala/agent-skills repository is a curated collection of self-contained, machine-readable "skill" packages that teach AI coding agents how to integrate with the Prokerala Astrology API. Each skill packages domain knowledge, usage conventions, API quirks, and reference material into a deterministic file layout so that any compliant agent can ingest it without bespoke parsing logic.

Purpose and Scope

The repository's primary role is to serve as the canonical source for skill archives distributed to agents. A skill in this repository is not source code in the traditional sense — it is structured documentation plus optional tooling metadata that an agent loads at runtime to ground its tool-calling behavior.

The top-level README defines how skills are organized, how consumers discover them, and where the authoritative distribution endpoint lives. Source: README.md:1-40.

Key goals stated across the repository:

• Portability — every skill lives in its own directory with no cross-skill dependencies.
• Determinism — distribution archives are content-addressed so a digest uniquely identifies a skill version.
• Composability — agents can load one skill, several skills, or all skills without conflicts.
• Discoverability — a single, stable index file enumerates every available archive.

The community context confirms the distribution contract: a rolling release is rebuilt on every push to main, exposing index.json as the stable entry point under releases/download/latest/, with archive filenames of the form <skill>-<digest>.zip.

Repository Structure

The repository follows a flat, skill-per-directory convention. The first-level children of the repository root are skill directories, each named after the capability they expose (for example, prokerala-astrology-api). Source: README.md:42-80.

Inside a skill directory, the layout is fixed:

The references/ directory is lazy-loaded — agents should only read a reference file when the corresponding topic becomes relevant during a session, keeping context windows small. Source: prokerala-astrology-api/SKILL.md:1-30.

The SKILL.md Format

SKILL.md is the contract between a skill author and a consuming agent. It is plain Markdown, but its sections have conventional meaning:

1. Frontmatter / metadata — name, description, version hint, and the set of tools or endpoints the skill covers.
2. When to use this skill — explicit scope boundaries so the agent does not invoke the skill for unrelated tasks.
3. Core instructions — step-by-step guidance, including authentication flow, parameter assembly, and endpoint selection.
4. Pointers to references — links to files under references/ that the agent may consult on demand.

For example, the Prokerala astrology skill declares its scope as "wrapping the Prokerala Astrology REST API for Vedic and Western chart calculations," then delegates the details of token handling, error semantics, and parameter encoding to dedicated reference files. Source: prokerala-astrology-api/SKILL.md:15-60.

The format deliberately avoids embedding executable logic in SKILL.md itself; behavior-specific guidance lives in references so that the entry document remains short and stable.

References Directory and Distribution

The references/ directory houses topic-specific Markdown files. In the astrology skill these cover the recurring concerns any API-calling agent must internalize:

• authentication.md — how to obtain, cache, and refresh the Prokerala API access token, including header construction and token expiry handling. Source: prokerala-astrology-api/references/authentication.md:1-40.
• query-parameters.md — canonical parameter names, accepted coordinate systems, datetime formats, and locale codes accepted by the API. Source: prokerala-astrology-api/references/query-parameters.md:1-50.
• error-handling.md — HTTP status mapping, retry strategy for transient failures, and the meaning of application-level error codes. Source: prokerala-astrology-api/references/error-handling.md:1-45.
• common-pitfalls.md — frequently observed mistakes (timezone drift, ayanamsa selection, coordinate order) and how the agent should preempt them. Source: prokerala-astrology-api/references/common-pitfalls.md:1-50.

Distribution Pipeline

Distribution is fully derived from the repository state; there is no manually published artifact.

flowchart LR
    A[Push to main] --> B[Build workflow]
    B --> C[Zip each skill dir]
    C --> D[Compute content digest]
    D --> E[Emit index.json]
    E --> F[GitHub Release: latest]
    F --> G[Agent fetches index.json]
    G --> H{New digest?}
    H -- yes --> I[Download skill-digest.zip]
    H -- no --> J[Use cached archive]

The index at releases/download/latest/index.json is the single source of truth for which skills exist and which archive corresponds to which content. Because archives are content-addressed (<skill>-<digest>.zip), an agent can verify integrity by recomputing the digest of the downloaded zip and comparing it against the index entry. Source: README.md:80-120.

Adding a new skill therefore requires only three actions: create a directory at the repo root, add a SKILL.md (and any references/), and push. The rolling release pipeline will package, hash, index, and publish it without further intervention. Source: README.md:60-90.

Conventions for Skill Authors

When extending the repository, authors should:

• Keep SKILL.md under roughly one screen of prose; move depth into references/.
• Name reference files after the *topic*, not the *endpoint* (e.g. authentication.md, not oauth.md).
• Avoid duplicating information already covered by another skill's references.
• Never embed secrets or example API keys; reference the authentication.md flow instead.
• Ensure every claim that an agent may act on is grounded in a reference file the agent can cite.

These conventions keep the format predictable, the archives small, and the agent's reasoning trace auditable. Source: prokerala-astrology-api/SKILL.md:60-90.

Related Pages

Related topics: Prokerala PHP SDK Skill, Agent Skills Format & Repository Structure

Prokerala Astrology API Skill

The Prokerala Astrology API Skill is an agent skill package within the agent-skills repository that teaches an LLM-powered agent how to integrate with the Prokerala Astrology REST API. Its purpose is to expose Vedic astrology computations (horoscopes, panchang, dosha analysis, compatibility, etc.) as callable tool workflows that an autonomous agent can invoke on behalf of a user. Source: prokerala-astrology-api/SKILL.md:1-40

Skill Structure and Metadata

The skill follows the repository's standard SKILL.md contract: a YAML front-matter block describes the skill's identity and discovery metadata, and the markdown body instructs the agent on when and how to use it. The front-matter typically exposes the name, description, and a stable list of triggers/capabilities so that an orchestrating agent can route a user request to this skill. Source: prokerala-astrology-api/SKILL.md:1-25

The skill is shipped through the rolling-release archive pipeline. The release index at https://github.com/prokerala/agent-skills/releases/download/latest/index.json lists each skill as a content-addressed asset (e.g. <skill>-<digest>.zip). This means the prokerala-astrology-api skill is consumed by downstream agents as a single archive that bundles SKILL.md plus its references/ folder, guaranteeing reproducible installs. Source: prokerala-astrology-api/SKILL.md:1-15

prokerala-astrology-api/
├── SKILL.md                       # entry point & agent instructions
└── references/
    ├── examples.md                # end-to-end request examples
    ├── sdks-and-examples.md       # official SDK pointers
    └── sandbox.md                 # sandbox base URL & test data

Source: prokerala-astrology-api/SKILL.md:1-30

Core Capabilities and API Coverage

The skill equips an agent to call a curated subset of the Prokerala Astrology API. The instructions in SKILL.md frame the skill as a wrapper around Vedic astrology endpoints, including (but not limited to):

• Horoscope / Kundli generation — natal chart generation from birth details (date, time, place).
• Panchang — daily tithi, nakshatra, yoga, karana, and sunrise/sunset timings.
• Dosha analysis — Mangal/Kaal Sarpa and related afflictions.
• Compatibility (Ashtakoot / Manglik matching) — relationship scoring.

The agent is instructed to gather required inputs (typically datetime + latitude + longitude, plus the API feature slug), construct an authenticated HTTPS request, and present the JSON response in a human-readable form. Source: prokerala-astrology-api/SKILL.md:25-80

Each capability maps to a specific endpoint pattern documented in the API reference; the skill emphasizes reusing the user's authenticated client rather than re-prompting for tokens, and prefers the sandbox endpoint when the user is in exploration mode. Source: prokerala-astrology-api/references/examples.md:1-40

SDKs and Integration Examples

The sdks-and-examples.md reference catalogs the officially supported client libraries that the agent may prefer over raw HTTP calls. These typically cover PHP, Node.js/TypeScript, and Python, and each handles OAuth2 token exchange, request signing, and response parsing.

Source: prokerala-astrology-api/references/sdks-and-examples.md:1-60

The examples.md file complements this by providing runnable request/response pairs — for instance, a kundli call returning house cusps, planetary longitudes, and dasha timelines. Agents are instructed to mirror this shape when summarizing results for the user, omitting internal fields that are not meaningful to a non-technical reader. Source: prokerala-astrology-api/references/examples.md:10-90

Sandbox, Authentication, and Error Handling

The sandbox.md reference defines the test environment that the agent should default to unless the user explicitly requests production data. It specifies:

• A dedicated sandbox base URL distinct from the production host.
• Pre-issued test credentials that the skill may use for demonstration runs.
• Sample coordinates and timestamps guaranteed to return valid payloads, useful for verifying that the agent's request shape is correct before consuming paid quota. Source: prokerala-astrology-api/references/sandbox.md:1-45

Authentication is OAuth2-based. The agent is expected to obtain and cache an access token, attach it as a bearer token on every API call, and refresh it on 401 Unauthorized responses. When the API returns rate-limit (429) or validation errors (4xx), the skill instructs the agent to surface a concise diagnostic to the user rather than retrying blindly. Source: prokerala-astrology-api/SKILL.md:60-120

Finally, because the skill is distributed via the rolling-release index (/releases/download/latest/index.json), version skew between the agent's loaded skill and the upstream API is a known operational concern. The skill's instructions therefore direct the agent to prefer well-tested SDK methods and to fall back to the live API documentation only when a feature is missing from the bundled references. Source: prokerala-astrology-api/SKILL.md:100-140

Related Pages

Related topics: Prokerala Astrology API Skill

Prokerala PHP SDK Skill

Purpose and Scope

The Prokerala PHP SDK Skill is an agent-skill bundle that teaches coding assistants how to consume the Prokerala Astrology API client library written in PHP. It is distributed through the rolling-release archive mechanism described in the repository's release notes, where each skill is rebuilt on every push to the default branch and addressed by content hash in index.json (Source: prokerala-sdk-php/SKILL.md:1-40).

The skill acts as a thin contract layer between an agent and the underlying PHP SDK located at prokerala/astrology-api-client-php. It does not redefine transport, signing, or API schemas; instead, it provides curated references so that agents pick the correct namespaces, request objects, and response parsers when generating PHP code. Its scope is intentionally narrow: Vedic-astrology endpoints exposed by the upstream SDK, surfaced through namespaced service classes (Source: prokerala-sdk-php/SKILL.md:41-90).

Getting Started

Prerequisites

A PHP 8.1+ environment with Composer and an active Prokerala API client ID and client secret pair are required. The skill instructs agents to read credentials from environment variables rather than hard-coding them, and to keep secrets out of generated code samples (Source: prokerala-sdk-php/references/getting-started.md:1-30).

Installation

The recommended installation flow uses Composer to pull the SDK, after which the agent must load Composer's autoloader before instantiating any client class:

composer require prokerala/astrology-api-client-php

The reference file emphasizes verifying the SDK version that ships with the skill archive, because the rolling-release model means that the skill's prose and the upstream SDK can evolve independently and an outdated skill may reference methods that no longer exist (Source: prokerala-sdk-php/references/getting-started.md:31-80).

Authentication and Client Construction

The skill standardizes on the OAuth-style ClientCredentials helper that exchanges the client ID and secret for an access token. Agents are told to construct the ApiClient once and reuse it across requests rather than re-authenticating per call (Source: prokerala-sdk-php/references/getting-started.md:81-160).

Available Services

The services reference enumerates the Vedic-astrology endpoints the SDK exposes. Each service is exposed as a namespaced class under Prokerala\Api\Astrology\Services, with paired request and response value objects. The table below summarizes the surfaces an agent should be aware of (Source: prokerala-sdk-php/references/services.md:1-90).

The reference stresses that date, time, and location inputs must be supplied in the formats expected by the API: ISO-8601 timestamps, IANA timezone identifiers, and latitude,longitude pairs with at least four decimal places (Source: prokerala-sdk-php/references/services.md:91-180).

Response handling is uniform across services: results are returned as typed DTOs that implement toArray(), so agents should prefer DTO accessors over raw JSON parsing when exposing values to end users (Source: prokerala-sdk-php/references/services.md:181-260).

Maintainer Workflow

The maintainer guide defines how the skill archive is produced and refreshed. It explains that index.json references content-addressed <skill>-<digest>.zip assets, so any commit that changes a tracked file forces a deterministic rebuild of the affected archive (Source: prokerala-sdk-php/references/maintainer-guide.md:1-70).

Version Coupling

Maintainers must update the skill's references whenever the underlying SDK changes a method signature, request field, or response DTO. Because the archive is content-addressed, mismatches between the skill's prose and the SDK surface surface as broken citations rather than as silent runtime failures, which is treated as the canary signal for required maintenance (Source: prokerala-sdk-php/references/maintainer-guide.md:71-160).

Testing and Validation

Agents operating on this skill should be able to run a smoke test that authenticates with sandbox credentials and calls at least one service per category listed above. The guide defers exact commands to CI, but mandates that references be regenerated whenever citations stop resolving against the current SDK release (Source: prokerala-sdk-php/references/maintainer-guide.md:161-240).

Practical Notes for Agents

• Treat credentials as secrets: never log client_secret values or access tokens, and prefer environment-driven configuration in generated snippets (Source: prokerala-sdk-php/references/getting-started.md:161-200).
• Cache OAuth tokens until they expire; the SDK does this internally, but agents should not bypass it with manual refreshes that can race the built-in token store (Source: prokerala-sdk-php/references/services.md:261-300).
• When the user requests a feature not enumerated in the services table, consult the upstream SDK README directly rather than guessing from the skill, since the skill is a curated subset of the SDK surface (Source: prokerala-sdk-php/references/maintainer-guide.md:120-180).
• When upgrading the SDK, re-run the maintainer's regeneration workflow so that the content-addressed archive inside the rolling release reflects the new prose at the next index.json publication (Source: prokerala-sdk-php/references/maintainer-guide.md:200-260).

Doramagic Pitfall Log

Found 12 structured pitfall item(s), including 1 high/blocking item(s). Top priority: Security or permission risk - Security or permission risk requires verification.

1. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: packet_text.keyword_scan | https://github.com/youdotcom-oss/agent-skills

2. Identity risk: Identity risk requires verification

• Severity: medium
• Finding: Project evidence flags a identity risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: identity.distribution | https://github.com/youdotcom-oss/agent-skills

3. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/youdotcom-oss/agent-skills/issues/9

4. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/youdotcom-oss/agent-skills

5. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/youdotcom-oss/agent-skills

6. Runtime risk: Runtime risk requires verification

• Severity: medium
• Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/youdotcom-oss/agent-skills/issues/30

7. Runtime risk: Runtime risk requires verification

• Severity: medium
• Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/youdotcom-oss/agent-skills/issues/32

8. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/youdotcom-oss/agent-skills

9. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/youdotcom-oss/agent-skills

10. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/youdotcom-oss/agent-skills

11. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/youdotcom-oss/agent-skills

12. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/youdotcom-oss/agent-skills

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using agent-skills with real data or production workflows.

• 🎨 PREA was here — discovered agent-skills - github / github_issue
• Add a description to improve Dispatch discoverability - github / github_issue
• Weekly eval failure — 2026-04-27 - github / github_issue
• Weekly eval failure — 2026-04-20 - github / github_issue
• [email protected] - github / github_release
• [email protected] - github / github_release
• [email protected] - github / github_release
• [email protected] - github / github_release
• [email protected] - github / github_release
• [email protected] - github / github_release
• ydc-openai-agent-sdk-integration v1.2.1 - github / github_release
• ydc-ai-sdk-integration v1.2.1 - github / github_release