#ifndef CST_SKILLS_H
#define CST_SKILLS_H

/*
 * Skills: directories with a SKILL.md (YAML frontmatter `name`,
 * `description`, then instructions) plus any helper files. Found in
 *   <ws>/.agent/skills/<dir>/   <ws>/.claude/skills/<dir>/
 *   <config>/skills/<dir>/      plugin skill roots (cst_skills_add_root)
 * The first skill of a name wins. The system prompt lists name +
 * description; the `skill` tool loads the rest on demand.
 */

#include "os_compat.h"

#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

#define CST_SKILLS_MAX 64
#define CST_SKILL_INDEX_MAX 4096

typedef struct {
  char name[64];
  char desc[600];
  char dir[OS_PATH_MAX];
  char source[48]; /* "workspace", "claude", "user", "plugin:<name>" */
} cst_skill_t;

/* Skills visible from workspace, sorted by name. Returns the count. */
int cst_skills_list(const char *workspace, cst_skill_t *out, int max);
/* Extra root (a directory of skill directories), e.g. from a plugin. */
void cst_skills_add_root(const char *dir, const char *source);
/* Forget the extra roots whose source starts with prefix ("" = all). */
void cst_skills_clear_roots(const char *source_prefix);
/* "Skills (...):\n- name: description\n" capped at CST_SKILL_INDEX_MAX, or
 * NULL when there are none. malloc'd. */
char *cst_skills_index(const char *workspace);
/* SKILL.md body (or one file of the skill) as tool output; *exit_code is 0
 * or 1. malloc'd. */
char *cst_skill_read(const char *workspace, const char *name,
                     const char *file, int *exit_code);
/* User message for `/skill name task`: the instructions inlined before the
 * task. NULL when the skill does not exist. malloc'd. */
char *cst_skill_prompt(const char *workspace, const char *name,
                       const char *task);
/* User message for `/init`: have the agent write AGENTS.md. */
const char *cst_init_prompt(void);
/* Register the `skill` tool (idempotent). */
int cst_skills_register_tool(void);

/* --- YAML-ish frontmatter (also used for agent role files) --- */
/* Value of key: plain, quoted, folded (`>`/`|`), `[a, b]` or `- a` lists
 * (lists come back comma-separated). Returns 1 when found. */
int cst_fm_get(const char *text, const char *key, char *out, size_t n);
/* Text after the closing `---` (the whole text when there is none). */
const char *cst_fm_body(const char *text);

#ifdef __cplusplus
}
#endif

#endif